# Miragea Voice MCP

> Open-source MCP (Model Context Protocol) server, written in Python, that lets AI agents (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf) generate voiceovers, multi-speaker dialogue and SRT/VTT subtitles, and transcribe audio/video into subtitles. It saves files to disk and returns their paths. Voice engine: the Miragea API (https://miragea.ai). Install: `uvx miragea-voice-mcp` with env `MIRAGEA_API_KEY`. License: MIT.

## Install

- Claude Desktop / Cursor / Windsurf: `{"mcpServers": {"miragea-voice": {"command": "uvx", "args": ["miragea-voice-mcp"], "env": {"MIRAGEA_API_KEY": "<key>"}}}}`
- Claude Code: `claude mcp add miragea-voice -e MIRAGEA_API_KEY=<key> -- uvx miragea-voice-mcp`
- Get a key: https://miragea.ai/workspace/api
- Check setup (no credits used): `uvx miragea-voice-mcp doctor`

## Tools

- text_to_speech(text, voice?, model?, format?, speed?, tags?, reference_text?, output_path?, subtitles?, max_credits?, fresh?): audio file + SRT/VTT; any text length.
- generate_dialogue(script, voices, gap_seconds?, speaker_labels?, ...): "Speaker: line" script → one audio file, per-line WAVs, speaker-labelled subtitles with exact line timings.
- transcribe_to_subtitles(file_path, formats?, output_dir?, max_credits?): local audio/video → SRT/VTT/TXT/JSON.
- list_voices(search?, limit?): saved voices (name, actor_id, language). Free.
- get_capabilities(): models, emotion tags, formats, limits, pricing. Free.
- estimate_cost(text, model?, voice_is_url?, with_reference_text?): credits estimate. Free.
- check_task(task_id, save?): resume a long task and save its result.
- list_recent_tasks(limit?): recent tasks and credits used.

## Key facts

- `voice` accepts a saved voice name, an actor_id, or a public https:// URL of a 5-30 s speech sample (zero-shot cloning).
- Default model `standard` (x1 credits per word; CJK per character). `expressive` is x1 with reference_text or a saved voice, x3 when cloning from a URL without reference_text.
- Subtitles from media are billed per second of media.
- Identical requests reuse the same idempotency key: retries never double-charge. `fresh=true` forces a new take.
- Files go to `~/miragea-voice` (env `MIRAGEA_OUTPUT_DIR`) and are never overwritten.
- `ffmpeg` is optional; without it, joined multi-part audio is saved as WAV.

## Docs

- [README](https://codeberg.org/miragea-voice/miragea-voice-mcp#readme)
- [Changelog](https://codeberg.org/miragea-voice/miragea-voice-mcp/src/branch/main/CHANGELOG.md)
- [Miragea API guide](https://miragea.ai/v1/guide)
