mcp-tts

What is mcp-tts?

mcp-tts is an MCP (Model Context Protocol) server that adds Text-to-Speech capabilities to AI assistants such as Claude Desktop and Cursor IDE. It provides four TTS tools – say_tts (macOS built-in), elevenlabs_tts, google_tts, and openai_tts – each powered by different speech synthesis engines.

How to use mcp-tts?

Install with go install github.com/blacktop/mcp-tts@latest. Configure the server in your MCP client’s settings (e.g., claude_desktop_config.json) with the required API keys for cloud-based tools. Once configured, the TTS tools can be called via the MCP protocol to speak text aloud through your computer’s speakers.

Key features of mcp-tts

• Four TTS backends: macOS say, ElevenLabs, Google Gemini, OpenAI
• Sequential speech mode prevents overlapping audio by default
• Multi-instance protection with a system-wide file lock
• Optional concurrent TTS mode for overlapping speech
• Suppress “Speaking:” output to keep LLM responses clean
• Save audio to disk (AIFF, MP3, WAV) with optional no-playback mode
• Speed control (0.25x–4.0x) and custom voice instructions for OpenAI

Use cases of mcp-tts

• Add spoken responses to AI assistants like Claude Desktop
• Coordinate speech in multi‑agent environments to avoid cacophony
• Generate audio files for offline playback or archiving
• Assign distinct voices per project for at‑a‑glance identification

FAQ from mcp-tts

What TTS tools does mcp-tts provide?

It provides four tools: say_tts (macOS built‑in), elevenlabs_tts, google_tts, and openai_tts. Each uses a different speech engine.

What API keys are required?

• ELEVENLABS_API_KEY for ElevenLabs
• GOOGLE_AI_API_KEY or GEMINI_API_KEY for Google TTS
• OPENAI_API_KEY for OpenAI TTS
  The say_tts tool works on macOS without any API key.

Can multiple agents speak at the same time?

By default, only one TTS request plays at a time – subsequent requests queue. Set MCP_TTS_ALLOW_CONCURRENT=true to allow overlapping speech.

How can I save audio to disk?

Set MCP_TTS_OUTPUT_DIR to a directory path. Optionally set MCP_TTS_NO_PLAY=true to skip playback and only save the file.

Does mcp-tts work on Windows or Linux?

The say_tts tool is macOS‑only. The other three tools work on any platform that has the required API keys and a working audio output.