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

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:

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.