tsuru0805/speak-aloud-mcp

git clone https://github.com/tsuru0805/speak-aloud-mcp && cd speak-aloud-mcp
pip install -e . (macOS/Linux) or pip install -e ".[windows]" (Windows adds pycaw for volume control).
Requires Python >=3.10 and the mcp SDK 1.19-1.x; PyPI package name speak-aloud-mcp is not yet published.

Usage

• •Set env: ELEVENLABS_API_KEY (must start with sk_), plus SPEAK_ALOUD_VOICES="mika=voice_id,..." or ELEVENLABS_VOICE_ID.
• •Sanity check first: speak-aloud-mcp --check then speak-aloud-mcp --say "你好，我在。" (non-zero exit if it couldn't be heard/played).
• •Claude Code: claude mcp add --transport stdio speak-aloud --env ELEVENLABS_API_KEY=... --env SPEAK_ALOUD_VOICES=... -- speak-aloud-mcp.
• •HTTP for shared use: speak-aloud-mcp --transport http --host 127.0.0.1 --port 8765 (endpoint /mcp); for claude.ai over a public tunnel add --allowed-host (the MCP SDK's DNS-rebinding guard rejects public hostnames otherwise).
• •Also usable without MCP: as a Python library (from speak_aloud_mcp import config, player, tts), as a CLI, or as an MCP client tool in your own gateway.

Key features

• ✓Honest receipts: played (file played fully), audible (false when known inaudible — still muted or volume 0), volume_during (read back, not configured), volume_state (restored/restore_unverified/restore_failed/untouched), note.
• ✓Playback needs no third-party Python audio libs — macOS afplay + osascript, Windows winsound (mp3 requires ffplay), Linux paplay/aplay + pactl (per-channel volumes preserved).
• ✓Core (config/tts/player) is MCP-free and importable without the mcp package.
• ✓Volume/mute are set before playback and restored + re-verified afterward; includes a process-level lock against concurrent playback races.
• ✓Environment-config only: SPEAK_ALOUD_VOLUME (default 35; off = don't touch), FORMAT (wav/mp3), CACHE_DIR, MAX_CHARS (default 1000), ELEVENLABS_MODEL_ID; MIT.

Best for

AI agents that live on a machine (e.g. a 24/7 Mac mini) and need to actually say something out loud, or deliver an audio file, with verifiable volume restoration.

Caveats

• ⚠Requires an ElevenLabs API key beginning with sk_ (key ID != key — wrong value yields "API key ID used as API key").
• ⚠Author honestly notes only macOS was production-tested; Windows/Linux paths are unit-tested (stubbed) but not yet run on real machines.
• ⚠The HTTP mode ships WITHOUT its own authentication — put a reverse-proxy Basic Auth or tunnel access control in front before exposing it.
• ⚠The lock preventing volume-state races is process-local: with multiple stdio servers on one machine, prefer one HTTP server for everyone.
• ⚠Audio files are not auto-cleaned (CACHE_DIR grows daily); ElevenLabs billing is per character, hence MAX_CHARS.