Miragea Voice MCP

Miragea Voice MCP is an open-source Model Context Protocol server that lets AI agents such as Claude Desktop, Claude Code, Cursor, VS Code and Windsurf create voiceovers and subtitles. Ask your agent to narrate a script, voice a multi-speaker dialogue, clone a voice from a short sample URL, or subtitle an existing video. The server saves real audio files (MP3, WAV, FLAC, Opus, AAC) and matching SRT/VTT subtitle files to disk and returns their paths. Speech is generated by the Miragea voice API. Setup is one uvx line and one API key.

You:    Narrate intro.md as a voiceover for my YouTube video, with subtitles.
Claude: Done. Saved ~/miragea-voice/intro.mp3, intro.srt and intro.vtt, and reported the duration and credits used.

Contents

• How it works
• Why this server
• Quick start
• Client setup: Claude Desktop · Claude Code · Cursor · VS Code · Windsurf
• Tools
• Configuration
• Writing multi-speaker scripts
• How subtitles are timed
• Credits and cost control
• Comparison with other TTS MCP servers
• FAQ
• Troubleshooting
• Development

How it works

Your MCP client starts miragea-voice-mcp locally over stdio. When the agent calls a tool, the server sends the request to the Miragea API, waits for the result, writes the audio and subtitle files to disk, and returns their absolute paths to the agent.

Why this server

Most text-to-speech MCP servers just play a sound or return a link. Making video, podcast or course content needs more than that:

• Files, not just sounds. Every tool writes to disk and returns absolute paths, ready for your editor, ffmpeg, or the next agent step. Existing files are never overwritten.
• Subtitles included. Every voiceover comes with .srt and .vtt timed to the actual audio. Existing media can be transcribed into subtitles as well.
• Multi-speaker in one call. Give it a Speaker: line script and a voice for each speaker. You get one joined audio file, one WAV per line for editing, and subtitles with speaker labels.
• Any length. Text over the per-request limit is split at sentence boundaries and joined back together.
• No double charges. Requests use deterministic idempotency keys, so a retry or a re-run returns the original task instead of paying again.
• Cost guard. Run estimate_cost first, and pass max_credits to stop a job before it starts if it would cost more.
• Errors your agent can act on. Each error has a stable code, a plain message and a Fix: line (bad key, no API access, out of credits, unknown voice, file too large, and so on).
• Light and cross-platform. Pure Python, no GPU, no model downloads. Works on macOS, Windows and Linux. ffmpeg is optional.
• Long jobs are safe. Progress notifications keep the client informed. If a wait times out, check_task picks the job up again. You never need to resubmit.

Quick start

1. Get a Miragea API key at miragea.ai/workspace/api. Free accounts can call the API by default; usage comes from your account's credits.
2. Install uv if you don't have it (curl -LsSf https://astral.sh/uv/install.sh | sh, or winget install astral-sh.uv on Windows).
3. Add the server to your client (Claude Desktop shown, others below):

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

4. Restart the client and try:

"List my Miragea voices, then read this paragraph in the warmest one and give me SRT subtitles."

Check your setup without spending credits:

MIRAGEA_API_KEY=... uvx miragea-voice-mcp doctor

Client setup

uvx miragea-voice-mcp config <client> prints a ready-to-paste snippet for claude-desktop, cursor, claude-code, vscode or windsurf.

claude mcp add miragea-voice -e MIRAGEA_API_KEY=<your-miragea-api-key> -- uvx miragea-voice-mcp

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

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

pip install miragea-voice-mcp
miragea-voice-mcp   # or: python -m miragea_voice_mcp

Tools

text_to_speech

Example result:

{
  "status": "succeeded",
  "audio_path": "/Users/you/miragea-voice/welcome-to-the-show-20261108-101500.mp3",
  "subtitle_paths": {
    "srt": "/Users/you/miragea-voice/welcome-to-the-show-20261108-101500.srt",
    "vtt": "/Users/you/miragea-voice/welcome-to-the-show-20261108-101500.vtt"
  },
  "duration_seconds": 6.84,
  "voice": "Ava",
  "model": "standard",
  "format": "mp3",
  "task_ids": ["3f2c..."],
  "credits_used": 14,
  "subtitle_timing": "estimated from measured audio duration (sentence-level)",
  "notes": []
}

generate_dialogue

The result includes each line's exact start/end in the final file, the joined audio path, and a segments_dir with one WAV per line.

transcribe_to_subtitles

Configuration

All configuration is through environment variables in your client's env block. Only the API key is required.

Writing multi-speaker scripts

Narrator: Welcome to Two Minute Tech.
Ava: Today's idea: the Model Context Protocol.
Leo: Wait, is that the thing that lets Claude use tools?
[pause 600ms]
Ava: Exactly.
And this line has no speaker, so Ava keeps talking.

• One utterance per line: Speaker: text. Lines with no speaker continue the previous speaker. Before the first speaker appears, they belong to Narrator.
• [pause 1.5s], [pause 800ms] or [pause 2] adds silence after the previous line.
• See examples/podcast-script.txt.

Lines are synthesized one by one as WAV and joined in pure Python, so no extra software is needed. If ffmpeg is installed, the joined file is converted to the format you asked for. Without it you get a WAV, and the result says so.

How subtitles are timed

Text-to-speech engines return audio without word timestamps. This server times subtitles in three ways:

1. Generated speech, single text. The text is split into readable cues (sentences, then clauses, at most about two lines of 42 characters each, with tighter limits for CJK). The measured audio duration is shared out by character weight, with extra weight for punctuation pauses. This is accurate to a fraction of a second for normal narration.
2. Dialogue and long text. Each line or chunk is its own audio segment, so its boundaries in the final file are exact. Only timing inside a line is estimated.
3. Existing media (transcribe_to_subtitles). Miragea's speech recognition gives timed segments. The punctuated transcript is then cut back into sentence cues and each cue is timed letter by letter from those segments, so no word is ever split across two cues.

Credits and cost control

Generation uses your Miragea account's credits. Live rates come from get_capabilities. At the time of writing:

• Speech, billed per word (per character for CJK). standard costs ×1. expressive costs ×1 with a saved voice or with reference_text, and ×3 when cloning from a URL without reference_text. Emotion tags are free.
• Subtitles from media, billed per second of media (currently 3 credits/second).
• Failed audio tasks are refunded automatically by Miragea.

The server's own safeguards:

• estimate_cost is free and runs locally.
• max_credits refuses a job before it starts if the estimate is higher.
• Deterministic idempotency keys mean a retry, timeout or accidental re-run returns the original task instead of charging again. Use fresh=true when you really want a new take.

Comparison with other TTS MCP servers

This comparison is based on each project's public README as of November 2026. "Not documented" means we couldn't find it, not that it's impossible. Corrections are welcome as PRs.

Where others are stronger: ElevenLabs' tool set is much broader (sound effects, voice design, agents, music). Local engines are free and work offline. FreeTTS lists thousands of stock voices and needs no install. Pick Miragea Voice MCP when you want production files with subtitles, multi-speaker scripts and predictable cost, from any OS, without a GPU.

FAQ

How do I add text-to-speech to Claude Desktop? Add the miragea-voice block from Quick start to claude_desktop_config.json with your Miragea API key and restart Claude. Then ask Claude to read any text aloud into a file.

How can Claude Code or Cursor generate a voiceover for my video? Install this server (see Client setup) and ask, for example: "Write a 30-second voiceover for this product demo, generate it with my 'Narrator' voice, and save it to ./assets/vo.mp3 with subtitles." The agent gets back the file paths and can drop them into your project.

How do I generate SRT subtitles from text with AI? text_to_speech writes .srt and .vtt next to every voiceover by default, timed to the generated audio. For a video you already have, use transcribe_to_subtitles.

How do I make a multi-speaker podcast or dialogue with AI voices? Write the script as Speaker: line and call generate_dialogue with one voice per speaker. You get a single audio file, a WAV per line and speaker-labelled subtitles.

Can I clone a voice with an MCP server? Yes. Pass a public https:// link to a clean 5–30 second speech sample as voice. Adding its exact transcript as reference_text improves quality and lowers the cost on the expressive model. You can also save voices in your Miragea account and use them by name. Only clone voices you have the right to use.

Is Miragea Voice MCP free? The server is free and MIT-licensed. Speech generation uses credits from your Miragea account. Free accounts can call the API by default, and estimate_cost tells you the price before you generate.

Where are the audio files saved? In ~/miragea-voice by default. Change it with MIRAGEA_OUTPUT_DIR or pass output_path per call. Files are never overwritten: a -2, -3… suffix is added instead.

Does it work offline? No. Speech is generated by the Miragea API, so you need an internet connection.

What languages and emotions are supported? Whatever your Miragea account offers. get_capabilities lists the live models and emotion/style tags, and list_voices shows each saved voice's language.

What if a long job times out in my client? The task keeps running on Miragea. Call check_task with the returned task_id, or simply repeat the same request: the idempotency key returns the original task, so you aren't charged twice.

Troubleshooting

Development

git clone https://codeberg.org/miragea-voice/miragea-voice-mcp
cd miragea-voice-mcp
uv venv && uv pip install -e ".[dev]"
uv run pytest          # tests use a mocked API: no key, no network, no credits
uv run ruff check src tests
npx @modelcontextprotocol/inspector uv run miragea-voice-mcp   # poke at the tools

Project layout:

src/miragea_voice_mcp/
  server.py     MCP tools (works with mcp 1.x FastMCP and mcp 2.x MCPServer)
  service.py    tool logic: voices, chunking, dialogue, transcription, files
  client.py     Miragea HTTP client: auth, polling, idempotency, downloads
  subtitles.py  cue splitting, timing, SRT/VTT/TXT writers
  audio.py      duration probing, WAV joining, optional ffmpeg transcode
  script.py     multi-speaker script parser
  cli.py        `doctor` and `config` commands

Contributions are welcome: open an issue first for larger changes.

License

MIT. The voice engine is the Miragea API, which has its own terms of service.