Dev.to AI 🤖 Ai Sun, 08 Nov 2026 13:05:03 +0000 👁 0 📖 6 min read

How to Give Claude, Cursor or Any AI Agent a Voice: Voiceovers and Subtitles with an MCP Server

You asked Claude to write a 60-second script for your next video. It did, in seconds. Then you copied the text into a text-to-speech website, downloaded an MP3, opened a subtitle editor, typed timings by hand, and dragged three files into your video editor. The AI wrote the words, but you still did all the production work.

The missing piece is a voice: a way for the agent itself to turn text into audio files and matching subtitles. This tutorial shows how to add one to Claude Desktop, Claude Code, Cursor, VS Code or any other MCP client using an open-source MCP server.

What is a voice MCP server?

A voice MCP server is a small program that speaks the Model Context Protocol and exposes text-to-speech and speech-to-text as tools an AI agent can call. The agent decides when to call them (for example, "narrate this script"), the server does the work, and the result comes back as data the agent can use in its next step. The server used here, miragea-voice-mcp, runs locally over stdio, uses the Miragea voice API as its speech engine, and always writes real files to disk (MP3, WAV, FLAC, Opus or AAC audio plus SRT and VTT subtitles) and returns their absolute paths, so the agent can hand them to ffmpeg, your editor, or another tool.

What can the agent do once it has a voice?

The server exposes eight tools:

Tool	What it does	Spends credits
`text_to_speech`	Text of any length → audio file + SRT/VTT subtitles	Yes
`generate_dialogue`	`Speaker: line` script → one joined audio file, per-line WAVs, speaker-labelled subtitles	Yes
`transcribe_to_subtitles`	Local audio or video → SRT, VTT, TXT, JSON	Yes
`list_voices`	Voices saved in your Miragea account	No
`get_capabilities`	Live models, emotion/style tags, formats, limits, pricing	No
`estimate_cost`	Credits a text would cost, before you generate it	No
`check_task`	Resume a long job by `task_id`	No
`list_recent_tasks`	Recent jobs with status and credits used	No

A few design choices matter for real production work:

Subtitles are timed to the generated audio, not guessed from word counts alone. For dialogue and long texts, each line is its own audio segment, so cue boundaries are exact.
Long text is split at sentence boundaries and joined back together, so you can voice a full script in one call.
Retries never double-charge. Requests use deterministic idempotency keys, so re-running the same request returns the original task.
Cost control is built in. estimate_cost is free, and max_credits stops a job before it starts if it would cost more than you allow.

How do I add a voice to Claude, Cursor or another AI agent? (3 steps)

Step 1: Get an API key and install uv

Create a Miragea API key at miragea.ai/workspace/api. The server itself is free and MIT-licensed; speech generation uses your Miragea account's credits.

The server is launched with uvx, which downloads and runs it from PyPI with no separate install step:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
winget install astral-sh.uv

Prefer pip? pip install miragea-voice-mcp works too, and the command is then just miragea-voice-mcp.

Step 2: Add the server to your MCP client

Claude Desktop: Settings → Developer → Edit Config, then add this to claude_desktop_config.json and restart Claude:

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

Cursor: put the same block in ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project).

Claude Code: one command.

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

VS Code (Copilot agent mode): add this to .vscode/mcp.json:

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

You don't have to copy these by hand: uvx miragea-voice-mcp config <client> prints the right snippet for claude-desktop, cursor, claude-code, vscode or windsurf.

Step 3: Check the setup, then ask for a voiceover

Run the built-in check. It verifies the key, the API connection and the output folder without spending any credits:

MIRAGEA_API_KEY=<your-miragea-api-key> uvx miragea-voice-mcp doctor

Then restart your client and ask in plain language:

"Estimate the cost first, then read intro.md as a calm voiceover and give me SRT and VTT subtitles."

Files land in ~/miragea-voice by default (change it with MIRAGEA_OUTPUT_DIR), and existing files are never overwritten.

3 real use cases for video creators

1. YouTube or course voiceover with subtitles in one prompt

Write or paste your script, then ask:

"Voice script.md with my 'Narrator' voice, save it to ./assets/vo.mp3, and create subtitles."

text_to_speech returns vo.mp3, vo.srt and vo.vtt. Because the agent receives the paths, it can keep going in the same conversation, for example by running ffmpeg to mux the audio and burn in the subtitles. If you haven't saved a voice in your account yet, pass a public https:// link to a clean 5–30 second speech sample as the voice to clone it (only clone voices you have the rights to use).

2. Two-host explainer or podcast-style dialogue

Write the script with one speaker per line:

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.

Then ask the agent to call generate_dialogue with a voice for each speaker. You get one joined audio file, a separate WAV per line (handy for fine-tuning in your editor), and subtitles with speaker labels: Ava: … in SRT and <v Ava> voice spans in VTT. Each line's exact start and end time in the final file comes back too.

3. Subtitles for footage you already recorded

For talking-head clips, screen recordings or interviews, ask:

"Create SRT and VTT subtitles for ./raw/interview.mp4."

transcribe_to_subtitles uploads the media to Miragea's speech recognition, then cuts the transcript into readable sentence cues and writes interview.srt, interview.vtt (plus TXT or JSON if you ask) next to the video. Pass max_credits if you want a hard budget, since this tool is billed by media duration.

FAQ

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

Add the miragea-voice block shown in Step 2 to claude_desktop_config.json, set your Miragea API key, and restart Claude Desktop. Claude can then call text_to_speech whenever you ask it to read, narrate or voice something.

Can Cursor or Claude Code generate a voiceover for my video project?

Yes. Both support MCP servers. Once the server is added, ask for a voiceover and an output path inside your project, such as ./assets/vo.mp3. The agent gets the file paths back and can wire them into your project.

How do I generate SRT subtitles from text with AI?

Use text_to_speech: it writes .srt and .vtt next to every voiceover by default, timed to the audio it just generated. For an existing video, use transcribe_to_subtitles.

Is it free?

The MCP server is free and open source (MIT). The speech itself is generated by the Miragea API and uses credits from your Miragea account. estimate_cost and get_capabilities are free and show the price before you generate anything.

Does it work offline?

No. Speech generation and transcription run on the Miragea API, so you need an internet connection. If you need fully offline TTS, a local engine is the better fit.

What happens if a long job times out in my client?

The task keeps running on the API side. Ask the agent to call check_task with the returned task_id, or simply repeat the request: the idempotency key returns the original task, so you aren't charged twice.

Which MCP clients are supported?

Any client that can launch a stdio MCP server: Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot agent mode), Windsurf and others. The command is always uvx miragea-voice-mcp with MIRAGEA_API_KEY in its environment.