OpenRouter Voice 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., "@OpenRouter Voice MCP Create voiceover MP3 for the script: 'Hello, welcome to my channel'."
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.
OpenRouter Voice MCP
A small MCP server (Python + FastMCP, stdio) that turns text into local audio files using OpenRouter speech models. Default model:
fish-audio/s2.1-pro-free:freeBuilt for Vietnamese video voiceover: Codex or Claude Code writes a narration
script, calls render_voiceover(), and gets back an absolute path to an MP3 it
can hand straight to FFmpeg.
Codex / Claude Code
| MCP stdio
OpenRouter Voice MCP
| HTTPS
OpenRouter -> fish-audio/s2.1-pro-free:free
|
MP3 bytes -> local file -> FFmpeg / video pipelineNo PyTorch, CUDA, local model downloads, local LLM, or local HTTP port. Just Python, three pure-Python packages and an OpenRouter API key.
Install
Requirements: Python >= 3.10 on PATH, plus ffmpeg if you want
render_long_voiceover() to concatenate segments. Get a free API key at
https://openrouter.ai/keys.
One command does everything -- venv, dependencies, .env, acceptance tests, and
registration with both Claude Code and Codex:
git clone https://github.com/Trandu1/mcp_voice.git D:\VoiceAI\openrouter-voice-mcp
cd D:\VoiceAI\openrouter-voice-mcp
.\install.ps1 -ApiKey "sk-or-v1-..." -RegisterManual equivalent, if you would rather see each step:
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
copy .env.example .env # then set OPENROUTER_API_KEY=sk-or-v1-...
.\.venv\Scripts\python.exe tests\acceptance.pyOn macOS / Linux there is no install.ps1; use the manual steps with
python3 -m venv .venv and .venv/bin/python, then register as shown below.
Register with Claude Code
claude mcp add openrouter-voice --scope user -- `
D:\VoiceAI\openrouter-voice-mcp\.venv\Scripts\python.exe `
D:\VoiceAI\openrouter-voice-mcp\server.py
claude mcp get openrouter-voice # expect: ConnectedRegister with Codex
codex mcp add openrouter-voice -- `
D:\VoiceAI\openrouter-voice-mcp\.venv\Scripts\python.exe `
D:\VoiceAI\openrouter-voice-mcp\server.py
codex mcp list # expect: openrouter-voiceThe API key is read from .env next to server.py, so it never appears on a
command line or in either CLI's config file. You can also export
OPENROUTER_API_KEY in the environment instead — an exported value wins over
.env.
Related MCP server: MCP MeloTTS Audio Generator
Tools
Tool | What it does |
| Config + key status. Free auth probe only, never renders audio. |
| The main tool. Text -> local audio file. |
| Splits a long script into segments, renders each, concatenates with FFmpeg when available. |
| Short sample, written to |
| Every OpenRouter model with |
| Live provider / tier / pricing / voice-cloning support for one model. |
render_voiceover
render_voiceover(
text: str,
output_path: str = "", # absolute or relative; parents are created
voice: str = "", # empty = model default (correct for Fish Audio)
response_format: str = "", # "mp3" (default) or "pcm"
instructions: str = "", # only sent to providers that document it
overwrite: bool = False, # False never clobbers an existing file
reference_audio_path: str = "", # optional stateless voice cloning
reference_text: str = "",
)Returns:
{
"status": "ok",
"model": "fish-audio/s2.1-pro-free:free",
"audio_path": "D:\\campaigns\\abc\\audio\\narration.mp3",
"format": "mp3",
"content_type": "audio/mpeg",
"bytes": 123456,
"elapsed_seconds": 2.31,
"duration_seconds": 12.4,
"generation_id": "gen-..."
}Audio bytes are written to disk and never returned base64-encoded through MCP — the point is a real file for FFmpeg.
Configuration
All settings are environment variables (see .env.example):
Variable | Default | Notes |
| — | Required. Never logged or returned. |
|
| |
| empty | Fish Audio documents no preset voice ids; leave empty. |
|
|
|
|
| |
| empty | Sent only when set. |
|
| Sent as |
|
| Used when the caller passes no |
| empty | Leave empty. Only set it if you accept being billed for a paid model when the free one is down. |
What the API actually supports
Verified against the live OpenRouter Speech API and Models API (2026-08-25), not inferred from the older OpenAI TTS API:
Endpoint
POST https://openrouter.ai/api/v1/audio/speechreturns a raw audio byte stream. Only non-200 responses carry JSON.Top-level fields:
model,input,voice,response_format,speed,input_references,provider.response_formatismp3orpcm. The API defaults topcm, so this server always sends the format explicitly.instructionsis not a top-level field. It is an OpenAI provider option (provider.options.openai.instructions). Fish Audio documents no provider options, soinstructionsis dropped for Fish models and reported back inwarnings— no invented fields are ever sent.speedis only honoured by some providers (OpenAI, Azure); it is dropped elsewhere rather than silently ignored server-side.Fish Audio has no preset voice ids (
alloy/nova/shimmerbelong to OpenAI). Leavevoiceempty.Voice cloning is available: the endpoints API reports
supports_voice_cloning: trueforfish-audio/s2.1-pro-free:free. It is stateless — you pass a base64 audio sample ininput_referenceson every request. There is no persistentvoice_idto create, so this server has noclone_voicetool; usereference_audio_pathonrender_voiceoverinstead.Attribution headers are
HTTP-RefererandX-OpenRouter-Title.
Free-model limits
fish-audio/s2.1-pro-free:free is a free variant:
20 requests/minute, 50 requests/day (1000/day once ≥ $10 of credit has been purchased on the account).
Availability, queueing and latency are not guaranteed.
When the free model is unavailable the server returns a clear error. It never switches to a paid model unless you explicitly set
OPENROUTER_VOICE_FALLBACK_MODEL.
Transient failures (408, 429, 5xx, network errors) are retried twice with short exponential backoff. 400/401/403 are never retried.
Tests
.\.venv\Scripts\python.exe -m pytest tests -q --asyncio-mode=auto # unit, mocked HTTP
.\.venv\Scripts\python.exe tests\smoke_test.py # live, needs a key
.\.venv\Scripts\python.exe tests\acceptance.py # full checklistsmoke_test.py and the live half of acceptance.py skip cleanly without a key.
A skip is reported as SKIP, never as PASS.
Security
The API key lives in
.env(git-ignored) or the environment. It is never logged, never written to a command line, and never returned through MCP.health()andmodel_info()return configuration, never credentials.The server speaks stdio only and binds no TCP port.
It executes no shell commands from tool input. FFmpeg/ffprobe are invoked only on files this server just wrote, and only when present.
File writes go exactly where the caller asks (Codex needs to write into arbitrary campaign directories), but directories, invalid Windows filenames and reserved device names are rejected, and
overwrite=Falsenever clobbers.
License
MIT
Available Tools
6 toolshealthA
Report MCP configuration status without spending a TTS request.
Checks that the API key is configured, echoes the active model, endpoint and output directory, and does one free auth probe against OpenRouter. The API key itself is never returned.
Inputs: no named parameters. Returns: object
list_speech_modelsA
List the OpenRouter models whose output modality is speech.
Returns id, name and pricing only. Use this to point OPENROUTER_VOICE_MODEL at a different provider without touching the code.
Inputs: no named parameters. Returns: object
model_infoA
Live details for the configured speech model (or the one you name).
Pricing, tier and voice-cloning support come from the OpenRouter endpoints API; anything OpenRouter does not report is returned as "unknown".
Inputs: model. Returns: object
preview_voiceA
Render a short sample so you can hear a voice before a full render.
Writes into <output_dir>/previews and, on Windows, opens it with the default player. Playback is best-effort: if it fails, audio_path is still returned.
Inputs: text (required), play, voice. Returns: object
render_long_voiceoverA
Render a long script by splitting it into segments and rendering each.
Splits on paragraph, then sentence, then word boundaries -- never mid-word. Short scripts fall through to a single request. When FFmpeg is available and the format is mp3, the segments are stream-copy concatenated into output_path; otherwise the segment paths are returned for the caller to join.
Inputs: text (required), voice, max_chars, overwrite, +2 more. Returns: object
render_voiceoverB
Render narration text to a local audio file via OpenRouter.
Inputs: text (required), voice, overwrite, output_path, +4 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: health for configuration status, preview_voice for a sample, render_voiceover for standard text-to-speech, render_long_voiceover for long scripts with splitting, list_speech_models for enumerating models, and model_info for details on a specific model. No overlaps in functionality.
Most tools follow a verb_noun pattern (preview_voice, render_voiceover, list_speech_models), but 'health' and 'model_info' are arguably nouns instead of commands. Minor inconsistency in verb usage, but overall naming is clear and predictable.
With 6 tools, the server is well-scoped for a text-to-speech utility. Each tool addresses a distinct need—status, preview, rendering, long rendering, model discovery, and model details—without unnecessary extras.
The tool surface covers the full lifecycle of using OpenRouter's TTS: checking configuration, previewing voices, rendering short and long audio, listing available models, and querying model attributes. No obvious dead ends or critical missing operations.
Related MCP Connectors
Text to speech and transcription for any AI model: MP3 voiceovers, audio and YouTube to text.
Audio for your agent: transcribe, speak, translate, summarise, plus sound effects and music.
Files to text for AI agents: audio/podcast transcription, OCR, video frames, screenshots, web to MD.
Remote text-to-speech MCP server with text_to_speech and list_voices tools. Free plan.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to generate and play high-quality text-to-speech audio using the Kokoro model, with support for multiple voices, adjustable speaking speed, and audio caching.-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to convert text to high-quality speech audio using MeloTTS. Automatically splits long texts into segments, generates WAV files, and merges them using ffmpeg with support for multiple languages and customizable speech parameters.MIT
- AlicenseNot gradedqualityDmaintenanceEnables text-to-speech generation using the Groq API, supporting multiple audio formats and optional local playback.33 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to synthesize speech via the unlimitedtts API, handling x402 micropayments, spend policy enforcement, and storage of private MP3 results.MIT