{ "markdown": "

\n \"mcp-tts\n

mcp-tts

\n

MCP Server for TTS (Text-to-Speech)

\n

\n \n \n \n \n \n \n \n \n \n \n

\n
\n\n## What? 🤔\n\nAdds Text-to-Speech to things like Claude Desktop and Cursor IDE. \n\nIt registers the existing TTS tools, plus `voice_tts` when `voice-say` is available on `PATH`:\n - `say_tts` \n - `voice_tts` (when available)\n - `elevenlabs_tts`\n - `google_tts`\n - `openai_tts`\n\n### `say_tts`\n\nUses the macOS `say` binary to speak the text with built-in system voices\n\n### `voice_tts`\n\nUses the local `voice-say` CLI from [Voice](https://github.com/blacktop/Voice) to run Qwen3-TTS through MLX. Voice needs no API key and keeps text and audio on the Mac. The model reloads for every invocation, so startup typically takes several seconds; prefer it for summaries and announcements rather than time-critical alerts.\n\nThe tool is registered only when `voice-say` is resolvable on `PATH`. Optional parameters are:\n\n- `voice`: preset voice `Ryan` or `Aiden`\n- `tier`: `small` for faster 0.6B synthesis or `large` for higher-quality 1.7B synthesis\n- `style`: free-text delivery guidance\n- `describe`: free-text voice design; forces the 1.7B model and cannot be combined with `voice`\n\nVoice plays audio directly and does not support `--output-dir`; with `--no-play`, calls fail without launching `voice-say`.\n\n> [!WARNING]\n> The Voice repository is currently private and will be released publicly soon, so the link requires access for now.\n\n### `elevenlabs_tts`\n\nUses the [ElevenLabs](https://elevenlabs.io/app/speech-synthesis/text-to-speech) text-to-speech API to speak the text with premium AI voices\n\n### `google_tts`\n\nUses Google's [Gemini TTS models](https://ai.google.dev/gemini-api/docs/speech-generation) to speak the text with 30 high-quality voices. Available voices include:\n\n**Achernar, Achird, Algenib, Algieba, Alnilam, Aoede, Autonoe, Callirrhoe, Charon, Despina, Enceladus, Erinome, Fenrir, Gacrux, Iapetus, Kore, Laomedeia, Leda, Orus, Puck, Pulcherrima, Rasalgethi, Sadachbia, Sadaltager, Schedar, Sulafat, Umbriel, Vindemiatrix, Zephyr, Zubenelgenubi**\n\n### `openai_tts`\n\nUses OpenAI's [Text-to-Speech API](https://platform.openai.com/docs/guides/text-to-speech) to speak the text with 10 natural-sounding voices:\n\n- **alloy** (Warm, conversational, modern)\n- **ash** (Confident, assertive, slightly textured)\n- **ballad** (Gentle, melodious, slightly lyrical)\n- **coral** (Cheerful, fresh, upbeat)\n- **echo** (Neutral, calm, balanced)\n- **fable** (Storyteller-like, expressive)\n- **nova** (Clear, precise, slightly formal)\n- **onyx** (Deep, authoritative, resonant)\n- **sage** (Soothing, empathetic, reassuring)\n- **shimmer** (Bright, animated, playful)\n- **verse** (Versatile, expressive)\n\nSupports three quality models:\n- **gpt-4o-mini-tts** - Default, optimized quality and speed\n- **tts-1** - Standard quality, faster generation \n- **tts-1-hd** - High definition audio, premium quality\n\nAdditional features:\n- Speed control from 0.25x to 4.0x (default: 1.0x)\n- Custom voice instructions (e.g., \"Speak in a cheerful and positive tone\") via parameter or `OPENAI_TTS_INSTRUCTIONS` environment variable\n\n## Configuration\n\n### Sequential vs Concurrent TTS\n\nBy default, the TTS server enforces sequential speech operations - only one TTS request can play audio at a time. This prevents multiple agents from speaking simultaneously and creating an unintelligible cacophony. Subsequent requests will wait in a queue until the current speech completes.\n\n**Multi-Instance Protection**: The mutex works both within a single MCP server process and across multiple Claude Desktop instances. When running multiple Claude Desktop terminals, they coordinate via a system-wide file lock to prevent overlapping speech.\n\nTo allow concurrent TTS operations (multiple speeches playing simultaneously):\n\n**Environment Variable:**\n```bash\nexport MCP_TTS_ALLOW_CONCURRENT=true\n```\n\n**Command Line Flag:**\n```bash\nmcp-tts --sequential-tts=false\n```\n\n> **Note:** Concurrent TTS may result in overlapping audio that's difficult to understand. Use this option only when you explicitly want multiple TTS operations to run simultaneously.\n\n### Suppressing \"Speaking:\" Output\n\nBy default, TTS tools return a message like \"Speaking: [text]\" when speech completes. This can interfere with LLM responses. To suppress this output:\n\n**Environment Variable:**\n```bash\nexport MCP_TTS_SUPPRESS_SPEAKING_OUTPUT=true\n```\n\n**Command Line Flag:**\n```bash\nmcp-tts --suppress-speaking-output\n```\n\nWhen enabled, tools return \"Speech completed\" instead of echoing the spoken text.\n\n### Saving Audio to Disk\n\nSave TTS audio output to files instead of (or in addition to) playing them:\n\n**Environment Variables:**\n```bash\nexport MCP_TTS_OUTPUT_DIR=/path/to/audio # Save audio files to this directory\nexport MCP_TTS_NO_PLAY=true # Skip playback, only save (optional)\n```\n\n**Command Line Flags:**\n```bash\nmcp-tts --output-dir /path/to/audio # Save and play\nmcp-tts --output-dir /path/to/audio --no-play # Save only, no playback\n```\n\nFiles are saved with unique names: `tts_{timestamp}_{hash}.{ext}`\n\n| Provider | Format |\n|----------|--------|\n| macOS say | AIFF |\n| Voice | Playback only |\n| ElevenLabs | MP3 |\n| Google TTS | WAV |\n| OpenAI TTS | MP3 |\n\n## Getting Started\n\n### Install\n\n```bash\ngo install github.com/blacktop/mcp-tts@latest\n```\n\n```bash\n❱ mcp-tts --help\n\nTTS (text-to-speech) MCP Server.\n\nProvides multiple text-to-speech services via MCP protocol:\n\n• say_tts - Uses macOS built-in 'say' command (macOS only)\n• voice_tts - Uses local Qwen3-TTS through voice-say (when available on PATH)\n• elevenlabs_tts - Uses ElevenLabs API for high-quality speech synthesis\n• google_tts - Uses Google's Gemini TTS models for natural speech\n• openai_tts - Uses OpenAI's TTS API with various voice options\n\nEach tool supports different voices, rates, and configuration options.\nRequires appropriate API keys for cloud-based services.\n\nDesigned to be used with the MCP (Model Context Protocol).\n\nUsage:\n mcp-tts [flags]\n\nFlags:\n -h, --help help for mcp-tts\n --no-play Skip playback, only save (requires --output-dir)\n --output-dir string Save audio files to directory (env: MCP_TTS_OUTPUT_DIR)\n --sequential-tts Enforce sequential TTS (prevent concurrent speech) (default true)\n --suppress-speaking-output Suppress 'Speaking:' text output\n -v, --verbose Enable verbose debug logging\n```\n\n### Configuration\n\n#### [Claude Desktop](https://claude.ai/download)\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"say\": {\n \"command\": \"mcp-tts\",\n \"env\": {\n \"ELEVENLABS_API_KEY\": \"********\",\n \"ELEVENLABS_VOICE_ID\": \"EXAVITQu4vr4xnSDxMaL\",\n \"GOOGLE_AI_API_KEY\": \"********\",\n \"OPENAI_API_KEY\": \"********\",\n \"OPENAI_TTS_INSTRUCTIONS\": \"Speak in a cheerful and positive tone\",\n \"MCP_TTS_SUPPRESS_SPEAKING_OUTPUT\": \"true\",\n \"MCP_TTS_ALLOW_CONCURRENT\": \"false\"\n }\n }\n }\n}\n```\n\n#### [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview)\n\n```bash\nclaude mcp add say \\\n -e GOOGLE_AI_API_KEY=your_key \\\n -e ELEVENLABS_API_KEY=your_key \\\n -e OPENAI_API_KEY=your_key \\\n -- mcp-tts\n```\n\n#### [Codex CLI](https://platform.openai.com/docs/guides/mcp)\n\n```bash\ncodex mcp add say \\\n --env GOOGLE_AI_API_KEY=your_key \\\n --env ELEVENLABS_API_KEY=your_key \\\n --env OPENAI_API_KEY=your_key \\\n -- mcp-tts\n```\n\n#### [Gemini CLI](https://github.com/google/gemini-cli)\n\n```bash\ngemini mcp add say mcp-tts \\\n -e GOOGLE_AI_API_KEY=your_key \\\n -e ELEVENLABS_API_KEY=your_key \\\n -e OPENAI_API_KEY=your_key\n```\n\nOr manually add to `~/.gemini/settings.json` (or `.gemini/settings.json` in project root):\n\n```json\n{\n \"mcpServers\": {\n \"say\": {\n \"command\": [\"mcp-tts\"],\n \"env\": {\n \"GOOGLE_AI_API_KEY\": \"...\"\n }\n }\n }\n}\n```\n\n#### Environment Variables\n\n- `ELEVENLABS_API_KEY`: Your ElevenLabs API key (required for `elevenlabs_tts`)\n- `ELEVENLABS_VOICE_ID`: ElevenLabs voice ID (optional, defaults to the premade \"Sarah\" voice `EXAVITQu4vr4xnSDxMaL`). Free-tier API keys can only use **premade** voices — Voice Library (community/professional) voices return `402 paid_plan_required`.\n- `GOOGLE_AI_API_KEY` or `GEMINI_API_KEY`: Your Google AI API key (required for `google_tts`)\n- `OPENAI_API_KEY`: Your OpenAI API key (required for `openai_tts`)\n- `OPENAI_TTS_INSTRUCTIONS`: Custom voice instructions for OpenAI TTS (optional, e.g., \"Speak in a cheerful and positive tone\")\n- `MCP_TTS_SUPPRESS_SPEAKING_OUTPUT`: Set to \"true\" to suppress \"Speaking:\" output (optional)\n- `MCP_TTS_ALLOW_CONCURRENT`: Set to \"true\" to allow concurrent TTS operations (optional, defaults to sequential)\n- `MCP_TTS_OUTPUT_DIR`: Directory to save audio files (optional)\n- `MCP_TTS_NO_PLAY`: Set to \"true\" to skip playback when saving (optional, requires `MCP_TTS_OUTPUT_DIR`)\n- `MCP_TTS_ELICIT`: Set to \"true\" to enable interactive elicitation prompts (also `--elicit`; optional, default off). When off, tools use explicit arguments/defaults without prompting — recommended for agent use.\n\n### Test\n\n#### Test macOS TTS\n```bash\n❱ cat test/say.json | go run main.go --verbose\n\n2025/03/23 22:41:49 INFO Starting MCP server name=\"Say TTS Service\" version=1.0.0\n2025/03/23 22:41:49 DEBU Say tool called request=\"{Request:{Method:tools/call Params:{Meta:}} Params:{Name:say_tts Arguments:map[text:Hello, world!] Meta:}}\"\n2025/03/23 22:41:49 DEBU Executing say command args=\"[--rate 200 Hello, world!]\"\n2025/03/23 22:41:49 INFO Speaking text text=\"Hello, world!\"\n```\n```json\n{\"jsonrpc\":\"2.0\",\"id\":3,\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"Speaking: Hello, world!\"}]}}\n```\n\n#### Test Google TTS\n```bash\n❱ cat test/google_tts.json | go run main.go --verbose\n\n2025/05/23 18:26:45 INFO Starting MCP server name=\"Say TTS Service\" version=\"\"\n2025/05/23 18:26:45 DEBU Google TTS tool called request=\"{...}\"\n2025/05/23 18:26:45 DEBU Generating TTS audio model=gemini-3.1-flash-tts-preview voice=Kore text=\"Hello! This is a test of Google's TTS API. How does it sound?\"\n2025/05/23 18:26:49 INFO Playing TTS audio via beep speaker bytes=181006\n2025/05/23 18:26:53 INFO Speaking via Google TTS text=\"Hello! This is a test of Google's TTS API. How does it sound?\" voice=Kore\n```\n```json\n{\"jsonrpc\":\"2.0\",\"id\":4,\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"Speaking: Hello! This is a test of Google's TTS API. How does it sound? (via Google TTS with voice Kore)\"}]}}\n```\n\n#### Test OpenAI TTS\n```bash\n❱ cat test/openai_tts.json | go run main.go --verbose\n\n2025/05/23 19:15:32 INFO Starting MCP server name=\"Say TTS Service\" version=\"\"\n2025/05/23 19:15:32 DEBU OpenAI TTS tool called request=\"{...}\"\n2025/05/23 19:15:32 DEBU Generating OpenAI TTS audio model=tts-1 voice=nova speed=1.2 text=\"Hello! This is a test of OpenAI's text-to-speech API. I'm using the nova voice at 1.2x speed.\"\n2025/05/23 19:15:34 DEBU Decoding MP3 stream from OpenAI\n2025/05/23 19:15:34 DEBU Initializing speaker for OpenAI TTS sampleRate=22050\n2025/05/23 19:15:36 INFO Speaking text via OpenAI TTS text=\"Hello! This is a test of OpenAI's text-to-speech API. I'm using the nova voice at 1.2x speed.\" voice=nova model=tts-1 speed=1.2\n```\n```json\n{\"jsonrpc\":\"2.0\",\"id\":5,\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"Speaking: Hello! This is a test of OpenAI's text-to-speech API. I'm using the nova voice at 1.2x speed. (via OpenAI TTS with voice nova)\"}]}}\n```\n\n#### Test the mutex behavior with multiple TTS requests\n\n```bash\n# Sequential mode (default) - speeches play one after another\ncat test/sequential.json | go run main.go --verbose\n\n# Concurrent mode - allows overlapping speech \ncat test/sequential.json | go run main.go --verbose --sequential-tts=false\n```\n\n## Skill: `speak`\n\nThis repo includes a **speak** skill that automatically announces plans, issues, and summaries aloud using TTS. It defaults to the host's macOS `say` voice, and can optionally assign distinct voices per project or message type so you can identify what is speaking from another room.\n\nSkills follow the [Agent Skills](https://agentskills.io) open standard and work across Claude Code, Codex CLI, and Gemini CLI.\n\n### Install Skill\n\n#### skills.sh\n\n```bash\nnpx skills add https://github.com/blacktop/mcp-tts --skill speak\n```\n\n#### Claude Code\n\n**Via Plugin Marketplace** (recommended):\n```bash\nclaude plugin marketplace add blacktop/mcp-tts\nclaude plugin install speak@mcp-tts\n```\n\n**Or manually:**\n```bash\nmkdir -p ~/.claude/skills\ngit clone https://github.com/blacktop/mcp-tts.git /tmp/mcp-tts\ncp -r /tmp/mcp-tts/skill ~/.claude/skills/speak\n```\n\nThe skill is now available. Claude will use it automatically when relevant, or invoke directly with `/speak`.\n\n#### Codex CLI\n\n**Using the skill-installer** (within a Codex session):\n```\n$skill-installer install the speak skill from https://github.com/blacktop/mcp-tts --path skill\n```\n\n**Or manually:**\n```bash\nmkdir -p ~/.codex/skills\ngit clone https://github.com/blacktop/mcp-tts.git /tmp/mcp-tts\ncp -r /tmp/mcp-tts/skill ~/.codex/skills/speak\n```\n\nRestart Codex after installing.\n\n#### Gemini CLI\n\nGemini CLI uses **extensions** to bundle skills. Install this repo as an extension:\n\n```bash\ngemini extensions install https://github.com/blacktop/mcp-tts.git\n```\n\nThis installs the `speak` skill.\n\n**Or manually** (skill only):\n```bash\nmkdir -p ~/.gemini/skills\ngit clone https://github.com/blacktop/mcp-tts.git /tmp/mcp-tts\ncp -r /tmp/mcp-tts/skill ~/.gemini/skills/speak\n```\n\n> **Note:** Gemini CLI skills are experimental. Enable via `/settings` → search \"Skills\" → toggle on.\n\n### Shared Skills Directory (Optional)\n\nTo maintain one copy across all agents, run the install script:\n\n```bash\ngit clone https://github.com/blacktop/mcp-tts.git\ncd mcp-tts\n./install-skill.sh\n```\n\nThis copies the skill to `~/.agents/skills/speak` and creates symlinks for Claude Code, Codex CLI, and Gemini CLI.\n\n### Verify Installation\n\n| Agent | Command |\n|-------|---------|\n| Claude Code | Ask \"What skills are available?\" or type `/speak` |\n| Codex CLI | Skills load automatically on restart |\n| Gemini CLI | `gemini extensions list` or check `/settings` for skills |\n\n### How It Works\n\nThe skill should be selected after:\n\n- **Planning complete** - When a plan/todo list is finalized\n- **Issue resolved** - When a bug fix or error is resolved\n- **Summary generated** - When completing a major task\n- **Long operation changes state** - When a build, test, deployment, release, research, or monitoring phase completes or fails\n- **Human intervention needed** - When approval, authentication, manual action, or an exhausted retry budget blocks progress\n\nThe skill defaults to local-only speech without probing credentials: `voice_tts` for plans and summaries when Voice is registered, and fast `say_tts` for urgent alerts or fallback. Both avoid cloud API quotas and keep spoken content on the Mac. Cloud TTS is used only after an explicit user choice or saved configuration. If that cloud provider hits a quota, token, authentication, or configuration failure, automatic cloud TTS is disabled for the session and the skill uses local speech—or remains text-only when no local tool is available. It never tries the other cloud providers automatically. One-off provider corrections last for the session; configuration is updated only when the user asks to remember the choice. For local `say` identity, leave `voice` unset to use the host System Voice unless the user intentionally selected an exact installed voice.\n\n## License\n\nMIT\n", "bytes": 16710, "sha": "367ce92f7d91766d74dd57602db80edf6cfd4312c5557fdf2fd927bd7410b835", "repo_slug": "blacktop/mcp-tts", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_blacktop_mcp_tts_28cb11d1/readme" }