# 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

```bash
uvx mcp-speak-when-done
```

### Claude Desktop / Claude Code

Add to your MCP configuration:

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

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

```bash
ssh -R 8000:localhost:8000 remote-server
```

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

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