Miragea MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Miragea MCP Read this changelog aloud in my voice and save it as release-notes.mp3"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Miragea MCP: voiceover, voice cloning and captions for Claude, Cursor and Codex
An MCP server that gives your AI agent a real voice toolkit: text of any length to speech in your saved
or cloned voice, exact durations for every file, readable SRT/VTT captions from any local audio or
video, and per-scene narration with durationInFrames and word-level captions for Remotion and other
video timelines. Local stdio server, one line of config, no GPU. Voice and speech recognition by
Miragea.
{
"mcpServers": {
"miragea": {
"command": "uvx",
"args": ["miragea-mcp"],
"env": { "MIRAGEA_API_KEY": "your_key", "MIRAGEA_VOICE_ID": "optional_default_voice" }
}
}
}Claude Code: claude mcp add miragea -e MIRAGEA_API_KEY=your_key -- uvx miragea-mcp.
No uv? pip install miragea-mcp and use "command": "miragea-mcp". Check everything with
uvx miragea-mcp --check.
Then just ask:
"Read this changelog aloud in my voice and save it as release-notes.mp3."
"Make captions for ~/Videos/talk.mp4." / "TikTok-style captions for clip.mov."
"Narrate these 5 scenes for my Remotion video and set each scene's durationInFrames."
Tools
Tool | What it does | Returns |
| Checks key, ffmpeg, saved voices, output folder; gives a fix for each problem | status + problems |
| Voices saved in your Miragea account |
|
| Any length of text to speech (split at sentence ends under the 2,000-char API limit, joined back seamlessly). Saved voice, or clone from a public clip | file path, exact seconds, chunks |
| Local audio/video to SRT + VTT: whole words (no mid-word splits), 2 x 42-char lines, min/max cue time; | srt/vtt paths, text, language |
| One audio file per scene, | manifest |
Related MCP server: narration-mcp
What it does for you automatically
Long text: chunked at sentence boundaries and stitched with a natural 120 ms pause. You never see the 2,000-character limit.
Durations: measured from the audio itself, so video timelines line up to the frame.
Captions: speech-recognition segments are rebuilt into whole words and re-flowed with broadcast rules.
Uploads: video files are reduced to a 16 kHz mono track before upload (fast, small).
Caching: the same text, voice and model is never billed twice; the same file is never transcribed twice.
Safety: existing files are never overwritten (
name-2.mp3), the key is only read from the environment and never logged, failed audio tasks are refunded by Miragea, and network retries reuse the same idempotency key so a retry cannot double-charge.Clear errors: every error comes back as
{"error", "how_to_fix"}for the agent to act on.
Compared with other voice MCP servers
miragea-mcp | ElevenLabs MCP | Thin TTS wrappers (Edge, Kokoro, Azure...) | |
Local stdio server, maintained | Yes | Local server deprecated; hosted OAuth server instead | Varies |
Reads/writes files anywhere you point it | Yes (default | Local version restricted inputs to one base folder | Usually output folder only |
Returns exact audio duration | Yes, every call | No (callers had to measure it) | Rarely |
Text longer than one API request | Automatic split and join | Manual | Varies |
Captions (SRT/VTT) from local files | Yes, reflowed whole words | Separate speech-to-text tool | No |
Scene durations in frames + Remotion captions | Yes ( | No | No |
Your own cloned voice | Saved voice id or reference clip | Yes (paid plans) | Stock voices only |
Billing | Pay-as-you-go Miragea points | Subscription credits | Free / cloud account |
Sources: ElevenLabs MCP README (deprecation notice) and the remotion-superpowers changelog (base-folder restriction, no duration returned).
Configuration
Env var | Required | Meaning |
| yes | Your key from miragea.ai |
| no | Default saved voice, so the agent never has to ask |
| no | Default reference clip (public URL) and its exact words |
| no | Where files go when no path is given (default |
Requirements: Python 3.10+. ffmpeg is optional (without it audio is saved as WAV and videos are uploaded whole).
FAQ
Which MCP clients work? Any stdio MCP client: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code (Copilot agent mode), Codex CLI, Gemini CLI, Cline, Zed.
How do I use my own voice? Save your voice once in your Miragea account and set MIRAGEA_VOICE_ID, or
pass reference_audio_url (a public link to a clean 5-20 s clip) with reference_text (its exact words,
which uses the cheaper 1x rate). A direct upload of local reference clips is planned by Miragea; until then
the reference must be a public URL.
What does it cost? Speech is billed per character, captions at 3 points per audio second (live rates:
GET https://miragea.ai/v1/capabilities). Cached repeats are free.
Is my key safe? It is read from the server's environment only, never written to disk, logged or returned.
Can I clone anyone's voice? No. Only clone your own voice or one you have permission to use.
Where are files saved? Where you ask, or in MIRAGEA_OUTPUT_DIR (default ~/Miragea). The cache lives in
~/Miragea/.cache and can be deleted at any time.
Related
miragea-skills: Agent Skills for screen-recording voiceover, Shorts, captions and Remotion narration.
Retake: fix a flubbed voiceover line in your own voice (CLI + MCP).
HeadVox: script to voiceover with word-aligned captions.
MIT License.
Available Tools
5 toolscheck_setupA
Check the API key, ffmpeg, saved voices and output folder, with a fix for every problem found.
Inputs: no named parameters.
list_voicesB
List voices saved in the user's Miragea account (ids to pass as voice_id).
Inputs: limit, offset.
narrate_scenesB
Voice a list of scenes (strings or {id, text}) as one audio file per scene and return each scene's exact seconds, durationInFrames and startFrame at the given fps, plus a narration.json manifest. captions=true also writes word-level captions.json in Remotion's Caption format. Unchanged scenes are cached and cost nothing on re-runs.
Inputs: scenes (required), fps, model, captions, +4 more.
speakA
Turn text of any length into speech in a saved voice (voice_id) or a voice cloned from a public clip (reference_audio_url + its exact words in reference_text, billed at the cheaper 1x rate). Returns the saved file path and its exact duration in seconds. format: mp3, wav, flac, opus, aac. model: 'expressive' (default) or 'standard'. speed: 0.25-4.
Inputs: text (required), model, speed, format, +4 more.
transcribeB
Transcribe a local audio or video file into readable SRT and VTT captions (whole words, line-length and timing rules applied). style: 'standard' (2 lines x 42 chars) or 'shorts' (1-3 words, uppercase). Results are cached, so asking again for the same file is free.
Inputs: path (required), style, output_dir.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct role: diagnostics (check_setup), voice enumeration (list_voices), single-text TTS (speak), caption generation from media (transcribe), and batch scene narration with frame timings (narrate_scenes). The only mild overlap is speak vs narrate_scenes, both doing TTS, but the descriptions make the boundary clear (single text+file path vs multi-scene timing manifest).
All five names are snake_case and verb-first (check_setup, list_voices, speak, transcribe, narrate_scenes), with no camelCase or style mixing. The pattern is predictable and readable throughout.
Five tools is well-scoped for a TTS/captioning server, with each tool earning its place (setup, voice discovery, synthesis, transcription, batch narration). Nothing feels redundant or padded.
The core lifecycle is covered: verify environment, discover voices, synthesize speech, transcribe media, and produce multi-scene narration with captions and manifests. Minor gaps exist—no tool to create/delete saved voices or to list/clean up generated output files—but agents can work around these via check_setup and speak's returned file path.
Maintenance
Related MCP Connectors
Generate and edit images, video, voice, lip-sync and 3D models from your AI agent.
Transcribe, subtitle, dub and lip-sync media; create speech, voices, images and thumbnails.
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
Audio for your agent: transcribe, speak, translate, summarise, plus sound effects and music.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to generate cinematic video and image assets and perform autonomous timeline assembly, multi-track audio editing, chroma-key compositing, and local draft manipulation from conversational prompts.3MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to generate narration in a single fixed, pre-approved voice, returning audio with per-line timing, hashes, and automatic quality checks on content, speaker identity, and pace, all locally and reproducibly.-
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to generate local GPU-accelerated narration audio from text, with tools for speech generation, job continuation, and model or voice queries.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to transcribe and summarize videos and voice messages, translate speech while keeping the speaker's voice, read text aloud in a cloned voice, and produce subtitles, lip-synced dubbing, voice changes, and translated images from links, uploads, or local files. It also handles media downloading and job/account status, with paid operations priced and confirmed before they run.MIT