TTS MCP Server

TTS MCP Server — text-to-speech, AI voiceover, voice cloning and SRT/VTT subtitles for Claude, Cursor and Codex

[CI] [Release] [PyPI] [Docker] [Python 3.10+] [Hugging Face Space] [License: MIT] [MCP]

tts-mcp-server is an open-source text-to-speech (TTS) MCP server that gives AI agents a voice. It lets Claude Desktop, Claude Code, Cursor, OpenAI Codex, VS Code and Windsurf turn a script into a narration audio file (MP3, WAV, FLAC, Opus, AAC or PCM) plus matching SRT and WebVTT subtitles in one Model Context Protocol tool call. It also clones a voice from a reference audio URL, uses the voices saved in your account, and transcribes any local audio or video file into captions. Text-to-speech, voice cloning and speech recognition run on the Miragea voice engine. Install it with one command, uvx tts-mcp-server; it needs only a MIRAGEA_API_KEY and is MIT licensed.

Install: uvx tts-mcp-server · pip install tts-mcp-server · docker run -i --rm -e MIRAGEA_API_KEY miragea/tts-mcp-server · Try it in the browser: live demo on Hugging Face Spaces · Source: github.com/RTY2345RR/miragea-voice-mcp

Formerly published as miragea-voice-mcp. The miragea-voice-mcp command is still installed as an alias, so existing configs keep working.

[Terminal screenshot: installing the voiceover and captions MCP server with uvx from GitHub, printing the Claude Code config, and listing its 7 MCP tools (text-to-speech, voice cloning, transcription to SRT/VTT)]

You:    Turn script.txt into a calm voiceover with captions for a YouTube Short.Agent:  miragea_script_to_voiceover(script_file="script.txt", actor_id="…", tags=["calm"])        → ~/Miragea/my-short.mp3  ~/Miragea/my-short.srt  ~/Miragea/my-short.vtt

Contents

• How it works
• Features
• Quickstart (60 seconds)
• Client setup: Claude Desktop, Claude Code, Cursor, Codex, VS Code, Windsurf
• Tools reference
• Examples with real output
• Example prompts
• Configuration
• How it compares
• FAQ
• Troubleshooting
• Agent Skill
• Development
• Links

How it works

[Architecture diagram of the voiceover and captions MCP server: an AI agent such as Claude, Cursor or Codex calls tts-mcp-server over MCP stdio; the server calls the Miragea voice engine for text-to-speech, voice cloning and speech recognition, and writes MP3 audio plus SRT and WebVTT captions]

1. Your AI agent (Claude Desktop, Claude Code, Cursor, OpenAI Codex, VS Code or Windsurf) calls a tool such as miragea_script_to_voiceover over the Model Context Protocol (stdio).
2. The server checks the request against the live voice-engine capabilities (models, emotion tags, formats, text length) and adds an idempotency key.
3. The Miragea voice engine generates the narration (or clones a voice from your reference clip), then runs speech recognition on the new audio for timestamps.
4. The server writes .mp3 + .srt + .vtt side by side, with captions that keep your exact script wording, ready to import into your video editor.

Features

• Script → voiceover + captions in one call. miragea_script_to_voiceover generates the narration, times captions by running Miragea speech recognition on the new audio, and writes .mp3 + .srt + .vtt side by side, ready for CapCut, Premiere Pro, DaVinci Resolve, YouTube, TikTok, Reels and Shorts.
• Captions spelled like your script. Recognition can mishear brand names ("Miragea" → "Mirage ear"). By default the server keeps the recognized timing but puts back your exact script wording, snapping cue breaks to sentence ends.
• Short-form friendly caption lengths. max_caption_chars (default 42 for scripts) splits long cues and shares their time by length, so captions stay readable on vertical video.
• Two voice sources. Use a voice already saved in your Miragea account (actor_id), or clone from a public reference audio URL (reference_audio_url + optional reference_text).
• Expressive or standard models, emotion tags, speed 0.25–4×. Options are read live from /capabilities, and every argument is validated before a job is submitted.
• Subtitles for any audio or video file. miragea_transcribe uploads mp3/wav/m4a/mp4/mov… and saves SRT, VTT, TXT or JSON (text, language, timed segments).
• No duplicate jobs on retry. Every job carries an Idempotency-Key; network errors and 502/503/504 are retried with the same key, so a retry never creates a second job. Timeouts return the task_id so the agent resumes with miragea_get_task instead of resubmitting.
• Never overwrites files. Existing outputs get -2, -3… suffixes.
• Secret-safe. The key is read from the environment, never logged, never echoed in errors, never sent to the audio download host, and API redirects are not followed.
• Starts without a key. Tool listing works with no key (handy for registries and inspectors); calls return a clear "set MIRAGEA_API_KEY" message.
• Works on MCP Python SDK 1.x and 2.x, Python 3.10–3.13, macOS, Windows and Linux. Two dependencies: mcp and httpx.

Quickstart (60 seconds)

1. Get a voice-engine key. The server uses Miragea for voiceover, voice cloning and recognition. Sign in and create an API key at miragea.ai/workspace/api. Setup guide: Install https://miragea.ai/skills/miragea-audio/install.md.
2. Install uv if you don't have it: curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or powershell -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows).
3. Add the server to your client (Claude Code shown; others below):

claude mcp add tts -s user -e MIRAGEA_API_KEY=<your-miragea-api-key> -- uvx tts-mcp-server

4. Verify (read-only, creates no job):

MIRAGEA_API_KEY=<your-miragea-api-key> uvx tts-mcp-server --check

Then ask your agent: "List my Miragea voices, then read 'Welcome back to the channel!' in the first English one."

Prefer pip? pip install tts-mcp-server and use "command": "tts-mcp-server" with no args in the snippets below. Prefer Docker? Use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MIRAGEA_API_KEY", "-v", "/path/to/output:/data", "miragea/tts-mcp-server"].

Client setup

Print any snippet with uvx tts-mcp-server --print-config <client> (claude-desktop, cursor, claude-code, codex, vscode, windsurf). Replace <your-miragea-api-key> and restart the client.

Claude Desktop

Settings → Developer → Edit Config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{  "mcpServers": {    "tts": {      "command": "uvx",      "args": ["tts-mcp-server"],      "env": { "MIRAGEA_API_KEY": "<your-miragea-api-key>" }    }  }}

Claude Code

claude mcp add tts -s user -e MIRAGEA_API_KEY=<your-miragea-api-key> -- uvx tts-mcp-server

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (project) — same JSON as Claude Desktop.

OpenAI Codex (CLI and IDE extension)

~/.codex/config.toml:

[mcp_servers.tts]command = "uvx"args = ["tts-mcp-server"]tool_timeout_sec = 900env = { MIRAGEA_API_KEY = "<your-miragea-api-key>" }

tool_timeout_sec matters: voiceover jobs can take longer than Codex's default tool timeout.

VS Code (Copilot agent mode)

.vscode/mcp.json:

{  "servers": {    "tts": {      "type": "stdio",      "command": "uvx",      "args": ["tts-mcp-server"],      "env": { "MIRAGEA_API_KEY": "<your-miragea-api-key>" }    }  }}

Windsurf

~/.codeium/windsurf/mcp_config.json — same JSON as Claude Desktop.

Tools reference

Every generation tool returns task_id, status and the idempotency_key it used, plus the saved file paths.

Examples

Real outputs from this server (Miragea voice engine), committed in examples/. Voices are cloned from CMU ARCTIC reference clips (licensed free for any use); the audiobook clip is from LibriSpeech (CC BY 4.0).

Transcription output (audiobook-clip.srt), with words kept whole across cues:

100:00:00,480 --> 00:00:01,987He hoped there would be stew for
200:00:01,987 --> 00:00:03,987dinner, turnips and carrots, and
300:00:03,987 --> 00:00:06,063bruised potatoes and fat mutton

Example prompts

• "Make a 30-second product-ad voiceover from ad.txt with my Nova voice, happy tone, 1.1× speed, and give me SRT + VTT with short captions."
• "Clone the voice at https://example.com/me.wav (it says: 'Hi, I'm Sam and this is my test.') and narrate intro.md as WAV."
• "Create subtitles for ~/Videos/vlog.mp4 as SRT and VTT."
• "That voiceover timed out — resume task … and save it to ~/Desktop/episode-3.mp3."
• "What models and emotion tags does my Miragea account have, and how many characters can I send per request?"

Configuration

How it compares

Honest snapshot from each project's public README (November 2026). "–" means not offered or not documented.

Where the others are ahead: ElevenLabs and AllVoiceLab cover more audio tasks (sound effects, voice changer, dubbing, agents), and better-tts-mcp needs no key and offers batch and multi-voice synthesis. This server stays focused on the video-creator loop of script → voiceover → captions and does that one loop end to end.

FAQ

What is a TTS MCP server?

A TTS (text-to-speech) MCP server is a small program that exposes speech synthesis as tools over the Model Context Protocol, so an AI agent such as Claude or Cursor can turn text into an audio file on request. tts-mcp-server adds voice cloning, speech-to-text subtitles and a one-call script → voiceover + SRT/VTT workflow on top.

How do I install a text to speech MCP server in Claude Code?

Run claude mcp add tts -s user -e MIRAGEA_API_KEY=<your-miragea-api-key> -- uvx tts-mcp-server, then ask Claude to "read this paragraph aloud and save it as MP3". Use uvx tts-mcp-server --print-config <client> for Claude Desktop, Cursor, Codex, VS Code or Windsurf.

Is there a free text to speech MCP server?

The server itself is free, open-source software (MIT). Speech is generated by the Miragea voice engine, so you need a Miragea API key. If you need a keyless option, better-tts-mcp uses Microsoft Edge read-aloud, and kokoro-tts-mcp runs a local model; neither does voice cloning or subtitles from your own audio.

Is this an alternative to the ElevenLabs MCP server?

Yes, for the voiceover use case. Like elevenlabs-mcp it installs with uvx and gives agents text-to-speech and voice cloning; unlike it, one tool call returns the audio together with SRT/VTT captions that keep your exact script wording. ElevenLabs covers more audio tasks (sound effects, voice changer, conversational agents); see How it compares.

How do I add text-to-speech to Claude Desktop?

Add the tts block from Claude Desktop to claude_desktop_config.json, put your Miragea API key in env, and restart Claude. Claude can then call miragea_text_to_speech and save MP3 files to ~/Miragea.

How do I generate SRT subtitles from a video with an AI agent?

Ask the agent to run miragea_transcribe on the file (for example, "make SRT and VTT subtitles for ~/Videos/clip.mp4"). The server uploads it to Miragea speech recognition and writes clip.srt / clip.vtt.

Can an MCP server make a voiceover with matching captions for YouTube Shorts or TikTok?

Yes. miragea_script_to_voiceover returns the audio plus SRT/VTT captions timed to that audio, with cues capped at 42 characters by default for vertical video. Import both into CapCut, Premiere Pro or DaVinci Resolve.

Does it support voice cloning?

Yes. Pass reference_audio_url (a public http(s) link to a clean sample) and, ideally, reference_text with the exact words spoken in it. Supplying the exact text gives the most faithful clone; if you omit it, Miragea recognizes it automatically. Only clone voices you have the right to use.

Does it work with Cursor, Claude Code and OpenAI Codex?

Yes, with any MCP client that supports stdio servers. Run uvx tts-mcp-server --print-config cursor (or claude-code, codex, vscode, windsurf, claude-desktop) for a ready snippet.

Which audio formats can I export?

MP3 (default), WAV, FLAC, Opus, AAC and PCM. Subtitles: SRT, WebVTT, plain text, and JSON with timed segments.

Can I use it without an API key or with another TTS engine?

No. Miragea is the only voice engine; there is no hidden fallback. Without a key the server still starts and lists its tools, and every call explains how to add the key.

Is my API key safe?

The key stays in your local MCP config or environment. The server never prints or logs it, redacts it from errors, sends it only to the Miragea API root (redirects are refused), and never sends it to the audio download URL.

What happens if a long voiceover times out?

The job keeps running on Miragea. The tool returns the task_id; ask the agent to call miragea_get_task with wait=true to download the result. Don't resubmit, because that would create a duplicate job.

Can I use it in Python scripts or n8n instead of chat?

Any MCP-capable runtime works. For plain scripts, call the Miragea REST API directly (guide, OpenAPI schema).

Troubleshooting

Logs go to stderr, which your client keeps (Claude Desktop on macOS: ~/Library/Logs/Claude/mcp-server-tts.log).

Companion Agent Skill

skills/miragea-voiceover/SKILL.md is an Agent Skill that teaches Claude a script-to-voiceover workflow on top of these tools: tightening a script for speech, choosing a voice and tone, confirming long jobs first, and delivering audio and captions for each platform. Copy the folder into ~/.claude/skills/ (Claude Code) or upload it as a skill in Claude. It is also published on its own in RTY2345RR/miragea-agent-skills with install steps for Claude Code, Codex and Cursor.

Development

git clone https://github.com/RTY2345RR/miragea-voice-mcp && cd miragea-voice-mcpuv venv && uv pip install -e ".[dev]"pytest                                   # offline; HTTP is mockednpx @modelcontextprotocol/inspector uvx --from . tts-mcp-server

The server wraps only the documented Miragea endpoints: GET /capabilities, GET /actors, POST /audio/generations, POST /subtitles/recognitions, GET /tasks/{id}, GET /tasks (API guide). VTT and short-cue splitting are local formatting of Miragea's timed segments.

Links

• GitHub: https://github.com/RTY2345RR/miragea-voice-mcp
• Live demo (Hugging Face Space): https://huggingface.co/spaces/miragea/miragea-voice-mcp
• Agent Skills: https://github.com/RTY2345RR/miragea-agent-skills
• Miragea API keys: https://miragea.ai/workspace/api
• PyPI: https://pypi.org/project/tts-mcp-server/
• Docker Hub: https://hub.docker.com/r/miragea/tts-mcp-server

License

MIT. "Miragea" is the voice engine this server connects to (voiceover, voice cloning, speech recognition). Use cloned voices only with the speaker's consent.