homeassistant-tts-mcp 0.1.0

MCP server that speaks text through the Home Assistant text-to-speech (tts.speak) service.

homeassistant-tts-mcp

An MCP server that speaks text out loud through your Home Assistant text-to-speech setup. It wraps the Home Assistant tts.speak service so any MCP-capable AI client (Claude Desktop, Claude Code, etc.) can talk through your speakers.

Tools

Tool	What it does
speak	Speak a message on a media player via a TTS engine (tts.speak).
list_media_players	List media_player.* entities you can target.
list_tts_engines	List tts.* engines and their supported languages.
check_connection	Verify the URL + token work.

Requirements

• A running Home Assistant instance with at least one TTS engine (Piper, Google Cloud, ElevenLabs, …) and a media player.
• A long-lived access token: Home Assistant → Profile → Security → Long-lived access tokens → Create token.
• uv / uvx to run it (Python 3.10+).

Configuration

The server is configured entirely through environment variables:

Variable	Required	Description
HA_URL	✅	Base URL, e.g. http://homeassistant.local:8123
HA_TOKEN	✅	Long-lived access token
HA_DEFAULT_MEDIA_PLAYER		Fallback media player for speak
HA_DEFAULT_TTS_ENTITY		Fallback TTS engine, e.g. tts.piper
HA_DEFAULT_VOICE		Fallback voice, e.g. en_US-hfc_female-medium
HA_DEFAULT_LANGUAGE		Fallback language code, e.g. en
HA_VERIFY_SSL		false to skip TLS verification (self-signed certs)
HA_TIMEOUT		HTTP timeout in seconds (default 30)

See .env.example.

Run it

Once published to PyPI:

uvx homeassistant-tts-mcp

The server speaks MCP over stdio, so you normally let your MCP client launch it. Example client config:

{
  "mcpServers": {
    "home-assistant-tts": {
      "command": "uvx",
      "args": ["homeassistant-tts-mcp"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your-long-lived-access-token",
        "HA_DEFAULT_MEDIA_PLAYER": "media_player.living_room",
        "HA_DEFAULT_TTS_ENTITY": "tts.piper"
      }
    }
  }
}

Then ask the assistant something like "Say 'dinner is ready' in the kitchen."

What speak sends

It maps directly onto the Home Assistant service call:

domain: tts
service: speak
entity_id: tts.piper                       # tts_entity_id
data:
  media_player_entity_id: media_player.living_room
  message: "Your spoken message goes here..."
  options:
    voice: en_US-hfc_female-medium         # when voice is provided

Development

uv sync                 # create venv + install deps (incl. dev group)
uv run homeassistant-tts-mcp   # run the server locally (needs HA_URL/HA_TOKEN)
uv run pytest           # tests
uv run ruff check .     # lint

Build & publish

uv build                              # produces dist/*.whl and *.tar.gz
uvx twine upload dist/*               # publish to PyPI
# then it's runnable anywhere as: uvx homeassistant-tts-mcp

License

MIT — see LICENSE.