mcp-tts 0.3.0

MCP Text-to-Speech Server for Cursor IDE (and others) with cross-platform audio playback

MCP Text-to-Speech for Cursor IDE

Add text-to-speech capabilities to Cursor IDE. Let your AI assistant speak responses, summaries, and explanations out loud.

🚀 Quick Start

Prerequisites: Cursor IDE and either an OpenAI API key or an ElevenLabs API key

Setup: Add one of these to your Cursor MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "mcp_tts_server": {
      "command": "uvx",
      "args": ["--from", "mcp-tts", "mcp-tts-server-stdio"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "ELEVENLABS_API_KEY": "your-elevenlabs-api-key-here",
        "MCP_TTS_PROVIDER": "openai",
        "MCP_TTS_VOICE": "ballad",
        "MCP_TTS_VOICE_PRESET": "default",
        "MCP_TTS_CUSTOM_INSTRUCTIONS": "",
        "MCP_TTS_SPEED": "1.0",
        "MCP_TTS_VOLUME": "0.8",
        "MCP_TTS_DEVICE_NAME": "",
        "MCP_TTS_DEVICE_INDEX": "",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

OpenAI (voices/presets/speed apply):

{
  "mcpServers": {
    "mcp_tts_server": {
      "command": "uvx",
      "args": ["--from", "mcp-tts", "mcp-tts-server-stdio"],
      "env": {
        "MCP_TTS_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-...",
        "MCP_TTS_VOICE": "alloy",
        "MCP_TTS_VOICE_PRESET": "professional",
        "MCP_TTS_CUSTOM_INSTRUCTIONS": "",
        "MCP_TTS_SPEED": "1.0",
        "MCP_TTS_VOLUME": "0.9",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

ElevenLabs (use voice_id or exact name; presets/speed are ignored):

{
  "mcpServers": {
    "mcp_tts_server": {
      "command": "uvx",
      "args": ["--from", "mcp-tts", "mcp-tts-server-stdio"],
      "env": {
        "MCP_TTS_PROVIDER": "elevenlabs",
        "ELEVENLABS_API_KEY": "eleven-...",
        "MCP_TTS_VOICE": "Adam",
        "MCP_TTS_VOLUME": "0.8",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

That's it! Restart Cursor and try asking: "Can you read me a summary using text-to-speech?"

⚙️ Configuration Options

You can control the TTS system using these environment variables in your MCP config:

Variable	Description	Example Values	Default
OPENAI_API_KEY	Your OpenAI API key (required if using OpenAI)	sk-proj-abc123...	-
ELEVENLABS_API_KEY	Your ElevenLabs API key (required if using ElevenLabs)	eleven-xxx...	-
MCP_TTS_PROVIDER	TTS provider to use	openai, elevenlabs	openai
MCP_TTS_VOICE	Voice selection	OpenAI: alloy, echo, ... • ElevenLabs: voice_id or exact name (case-insensitive)	ballad
MCP_TTS_VOICE_PRESET	Voice style preset	default, professional, calm, nyc_cabbie, chill_surfer, cheerleader, emo_teenager, eternal_optimist, dramatic	default
MCP_TTS_CUSTOM_INSTRUCTIONS	Custom voice instructions (overrides preset)	"Speak like a pirate"	-
MCP_TTS_SPEED	Speech speed	OpenAI: 0.25 to 4.0 • ElevenLabs: ignored	1.0
MCP_TTS_VOLUME	Playback volume	0.0 to 1.0	0.8
MCP_TTS_DEVICE_NAME	Audio device name (partial match)	"Speakers", "Headphones"	-
MCP_TTS_DEVICE_INDEX	Audio device index	0, 1, 2, etc.	-

Tips:

• Open the local Config page to pick an ElevenLabs voice from your account (with previews), or call their API and paste a voice_id.
• OpenAI accepts built-in voice names and presets; ElevenLabs uses voice_id or exact voice name. Presets/instructions/speed are ignored by ElevenLabs.

Voice Presets

You can use these built-in voice style presets:

• default - Clear, friendly, and conversational
• professional - Authoritative business voice
• calm - Composed, reassuring with quiet authority
• nyc_cabbie - Fast-talking New Yorker with edge
• chill_surfer - Laid-back, mellow, effortlessly cool
• cheerleader - High-energy, enthusiastic, motivational
• emo_teenager - Sarcastic, disinterested, melancholic
• eternal_optimist - Positive, solution-oriented
• dramatic - Low, hushed, suspenseful with theatrical flair

🎵 Usage Examples

• "Use text-to-speech to explain this code"
• "Read me the changes you just made"
• "List my audio devices"
• "Switch to a professional voice style"

📚 Full Documentation

For advanced configuration, voice presets, troubleshooting, and development setup, see SETUP_GUIDE.md.

---

Status: ✅ Working with Cursor IDE • 🎵 7 TTS tools available • 🔊 Cross-platform audio • 🧩 Providers: OpenAI, ElevenLabs

🛠️ Available Tools

This MCP server provides the following tools in Cursor:

• text_to_speech — Convert text to speech and play it through your speakers using the current configuration.
• list_audio_devices — List all available audio output devices on your system.
• test_audio_device — Play a test tone on a selected audio device to verify it works.
• stop_speech — Stop any current speech playback immediately.
• get_tts_status — Show the current TTS server status, provider, volume, and device info.
• get_current_config — Display the current voice, preset, device, and all active TTS settings.
• set_volume — Change the playback volume for speech output.