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:free

Built 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 pipeline

No 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-..." -Register

Manual 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.py

On 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: Connected

Register 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-voice

The 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.

---

Tools

Tool	What it does
health()	Config + key status. Free auth probe only, never renders audio.
render_voiceover(...)	The main tool. Text -> local audio file.
render_long_voiceover(...)	Splits a long script into segments, renders each, concatenates with FFmpeg when available.
preview_voice(text, voice)	Short sample, written to <output_dir>/previews and opened in the default player.
list_speech_models()	Every OpenRouter model with output_modalities: speech (id, name, pricing).
model_info(model)	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
OPENROUTER_API_KEY	—	Required. Never logged or returned.
OPENROUTER_VOICE_MODEL	fish-audio/s2.1-pro-free:free
OPENROUTER_VOICE	empty	Fish Audio documents no preset voice ids; leave empty.
OPENROUTER_AUDIO_FORMAT	mp3	mp3 or pcm.
OPENROUTER_TIMEOUT_SECONDS	120
OPENROUTER_HTTP_REFERER	empty	Sent only when set.
OPENROUTER_APP_TITLE	OpenRouter Voice MCP	Sent as X-OpenRouter-Title.
VOICE_OUTPUT_DIR	%USERPROFILE%\OpenRouterVoice\output	Used when the caller passes no output_path.
OPENROUTER_VOICE_FALLBACK_MODEL	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/speech returns a raw audio byte stream. Only non-200 responses carry JSON.
• Top-level fields: model, input, voice, response_format, speed, input_references, provider.
• response_format is mp3 or pcm. The API defaults to pcm, so this server always sends the format explicitly.
• instructions is not a top-level field. It is an OpenAI provider option (provider.options.openai.instructions). Fish Audio documents no provider options, so instructions is dropped for Fish models and reported back in warnings — no invented fields are ever sent.
• speed is 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 / shimmer belong to OpenAI). Leave voice empty.
• Voice cloning is available: the endpoints API reports supports_voice_cloning: true for fish-audio/s2.1-pro-free:free. It is stateless — you pass a base64 audio sample in input_references on every request. There is no persistent voice_id to create, so this server has no clone_voice tool; use reference_audio_path on render_voiceover instead.
• Attribution headers are HTTP-Referer and X-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 checklist

smoke_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() and model_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=False never clobbers.

License

MIT