# tts-mcp-server: Text-to-Speech (TTS) MCP Server for AI agents

> tts-mcp-server is an open-source (MIT) text-to-speech MCP server that gives AI agents (Claude Desktop, Claude Code, Cursor, OpenAI Codex, VS Code, Windsurf) a voice: it turns a script into a narration audio file plus SRT and WebVTT subtitles in one tool call, clones a voice from a reference audio URL, and transcribes audio or video into captions. Text-to-speech, voice cloning and speech recognition run on the Miragea voice engine (https://miragea.ai). Install: `uvx tts-mcp-server` (PyPI), `pip install tts-mcp-server`, or `docker run -i --rm -e MIRAGEA_API_KEY miragea/tts-mcp-server`. Requires the MIRAGEA_API_KEY environment variable (create one at https://miragea.ai/workspace/api; setup guide: https://miragea.ai/skills/miragea-audio/install.md).

Key facts:
- Package: tts-mcp-server on PyPI (https://pypi.org/project/tts-mcp-server/); Docker image miragea/tts-mcp-server (https://hub.docker.com/r/miragea/tts-mcp-server); MCP Registry name io.github.RTY2345RR/tts-mcp-server. Formerly published as miragea-voice-mcp; that command is still installed as an alias.
- Transport: stdio. Source: https://github.com/RTY2345RR/miragea-voice-mcp. Demo: https://huggingface.co/spaces/miragea/miragea-voice-mcp. Python 3.10+. Dependencies: mcp, httpx.
- Engine: the Miragea API only (base URL https://miragea.ai/v1). There is no third-party TTS fallback.
- Voices: saved account voices (`actor_id`) or cloning from a public reference audio URL (`reference_audio_url` + optional exact `reference_text`).
- Models: `expressive` and `standard`; emotion/style `tags` per model; speed 0.25–4; audio formats mp3, wav, flac, opus, aac, pcm.
- Subtitles: SRT, VTT, TXT, JSON from any local audio or video file; words that recognition cuts across two cues are re-joined; `max_caption_chars` for short-form video.
- Reliability: no duplicate jobs on retry (idempotency keys on every job, retries reuse the same key), timeouts return a resumable task_id, the key is never logged, and output files are never overwritten.

## Tools
- miragea_get_capabilities: live models, tags, formats, limits (read-only)
- miragea_list_voices: account voices, with search (read-only)
- miragea_text_to_speech: text → audio file
- miragea_transcribe: audio/video → SRT/VTT/TXT/JSON
- miragea_script_to_voiceover: script → audio + captions with exact script wording
- miragea_get_task: resume or download a job by task_id
- miragea_list_tasks: recent jobs

## Docs
- [README](https://github.com/RTY2345RR/miragea-voice-mcp#readme): quickstart, client configs, tools reference, examples, comparison, FAQ, troubleshooting
- [Examples with real output (MP3 + SRT)](https://github.com/RTY2345RR/miragea-voice-mcp/tree/main/examples)
- [Agent Skill](https://github.com/RTY2345RR/miragea-voice-mcp/blob/main/skills/miragea-voiceover/SKILL.md): script-to-voiceover workflow
- [Miragea setup guide](https://miragea.ai/skills/miragea-audio/install.md)
- [Miragea API guide](https://miragea.ai/v1/guide)
- [Miragea OpenAPI schema](https://miragea.ai/v1/schema)
- [Architecture diagram](https://github.com/RTY2345RR/miragea-voice-mcp/blob/main/docs/images/voiceover-captions-mcp-architecture-diagram.svg): agent → MCP stdio → tts-mcp-server → Miragea voice engine → MP3 + SRT + VTT
- [Changelog](https://github.com/RTY2345RR/miragea-voice-mcp/blob/main/CHANGELOG.md)

## Config snippet (Claude Desktop / Cursor / Windsurf)
{"mcpServers":{"tts":{"command":"uvx","args":["tts-mcp-server"],"env":{"MIRAGEA_API_KEY":"<your-miragea-api-key>"}}}}

## FAQ
- What is a TTS MCP server? A program that exposes text-to-speech as Model Context Protocol tools so an AI agent can turn text into audio files on request.
- How do I add text to speech to Claude Code? `claude mcp add tts -s user -e MIRAGEA_API_KEY=<key> -- uvx tts-mcp-server`.
- Is it an ElevenLabs MCP alternative? For voiceover work, yes: TTS and voice cloning via uvx, plus SRT/VTT captions in the same call. ElevenLabs' server covers more audio tasks (sound effects, voice changer, agents).
