mcp-speak-when-done

An MCP server that makes AI agents speak a brief summary of every response out loud.

When installed, the agent sees a speak_when_done tool with instructions to call it at the end of every response with a 1-3 sentence spoken summary.

Install

uvx mcp-speak-when-done

Claude Desktop / Claude Code

Add to your MCP configuration:

{
  "mcpServers": {
    "speak-when-done": {
      "command": "uvx",
      "args": ["mcp-speak-when-done"],
      "env": {
        "OPENAI_API_KEY": "your-api-key"
      }
    }
  }
}

Works with any OpenAI-compatible TTS API. The provider is auto-detected from your API key:

Key prefix	Provider	Default model	Default voice
gsk_	Groq	canopylabs/orpheus-v1-english	troy
(other)	OpenAI	tts-1	alloy

Requirements

One audio player must be installed: ffplay (from ffmpeg), mplayer, or vlc.

Configuration

All settings are optional environment variables:

Variable	Description	Default
OPENAI_API_KEY	API key (required)	—
SPEECH_VOICE	Voice name	auto-detected from key
SPEECH_SPEED	Speech speed	1.0
SPEECH_MODEL	TTS model	auto-detected from key
SPEECH_API_URL	API endpoint	auto-detected from key
SPEECH_MAX_RETRIES	Retry count	3
SPEECH_TIMEOUT	Request timeout (s)	30

Remote Use (SSH + SSE)

If you run Claude on a remote server but want audio on your local machine:

1. On your local machine (has speakers + API key):

OPENAI_API_KEY="your-key" mcp-speak-when-done --transport sse

This starts an SSE server on port 8000 (override with FASTMCP_PORT).

2. SSH tunnel from the remote server to your local machine:

ssh -R 8000:localhost:8000 remote-server

3. On the remote server, configure Claude with proxy mode:

{
  "mcpServers": {
    "speak-when-done": {
      "command": "uvx",
      "args": ["mcp-speak-when-done"],
      "env": {
        "SPEECH_PROXY_URL": "http://localhost:8000/sse"
      }
    }
  }
}

No API key needed on the remote side. If your local machine is off, the tool silently returns success — Claude keeps working normally.

Variable	Description	Default
SPEECH_PROXY_URL	SSE server URL	— (unset = direct mode)
SPEECH_PROXY_TIMEOUT	Proxy timeout (s)	10

License

GPL-3.0-or-later