Metadata-Version: 2.4
Name: homeassistant-tts-mcp
Version: 0.1.0
Summary: MCP server that speaks text through the Home Assistant text-to-speech (tts.speak) service.
Project-URL: Homepage, https://github.com/eitanhadar/homeassistant-tts-mcp
Project-URL: Repository, https://github.com/eitanhadar/homeassistant-tts-mcp
Project-URL: Issues, https://github.com/eitanhadar/homeassistant-tts-mcp/issues
Author-email: Eitan Hadar <eitanhadar4@gmail.com>
License: MIT
License-File: LICENSE
Keywords: home-assistant,homeassistant,mcp,text-to-speech,tts,voice
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2.0
Description-Content-Type: text/markdown

# homeassistant-tts-mcp

An [MCP](https://modelcontextprotocol.io) 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`](https://docs.astral.sh/uv/) 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`](.env.example).

## Run it

Once published to PyPI:

```bash
uvx homeassistant-tts-mcp
```

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

```json
{
  "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:

```yaml
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

```bash
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

```bash
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](LICENSE).
