OpenRouter Voice MCP
OpenRouter Voice MCP
一个轻量级 MCP 服务器(Python + FastMCP,stdio),使用 OpenRouter 语音模型将文本转换为本地音频文件。默认模型:
fish-audio/s2.1-pro-free:free专为越南语视频配音而构建:Codex 或 Claude Code 编写旁白脚本,调用 render_voiceover(),然后获得一个可以直接交给 FFmpeg 的 MP3 绝对路径。
Codex / Claude Code
| MCP stdio
OpenRouter Voice MCP
| HTTPS
OpenRouter -> fish-audio/s2.1-pro-free:free
|
MP3 bytes -> local file -> FFmpeg / video pipeline无需 PyTorch、CUDA、本地模型下载、本地 LLM 或本地 HTTP 端口。只需要 Python、三个纯 Python 包和一个 OpenRouter API 密钥。
安装
要求:Python >= 3.10 已加入 PATH,另外如果你需要 render_long_voiceover() 拼接音频片段,还需要 ffmpeg。在 https://openrouter.ai/keys 获取免费 API 密钥。
一条命令完成所有操作——虚拟环境、依赖、.env、验收测试,以及向 Claude Code 和 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手动等效步骤,如果你更想逐步查看:
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在 macOS / Linux 上没有 install.ps1;请使用手动步骤,用 python3 -m venv .venv 和 .venv/bin/python,然后按下方说明注册。
注册到 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注册到 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-voiceAPI 密钥从 server.py 旁边的 .env 读取,因此它永远不会出现在命令行或任一 CLI 的配置文件中。你也可以在环境中导出 OPENROUTER_API_KEY——导出的值优先于 .env。
Related MCP server: MCP MeloTTS Audio Generator
工具
工具 | 功能 |
| 配置 + 密钥状态。仅免费认证探测,绝不渲染音频。 |
| 主要工具。 文本 -> 本地音频文件。 |
| 将长脚本拆分为多个片段,逐个渲染,在可用时用 FFmpeg 拼接。 |
| 短样本,写入 |
| 所有 |
| 单个模型的实时提供商 / 层级 / 定价 / 声音克隆支持。 |
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 = "",
)返回:
{
"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-..."
}音频字节写入磁盘,绝不通过 MCP 以 base64 编码返回——关键在于生成一个可供 FFmpeg 使用的真实文件。
配置
所有设置均为环境变量(参见 .env.example):
变量 | 默认值 | 说明 |
| — | 必填。绝不记录日志或返回。 |
|
| |
| 空 | Fish Audio 未记录预设声音 id;留空即可。 |
|
|
|
|
| |
| 空 | 仅在设置时发送。 |
|
| 作为 |
|
| 当调用方未传入 |
| 空 | 留空。 仅当你接受在免费模型不可用时为付费模型付费,才设置此项。 |
API 实际支持的内容
已针对实时 OpenRouter Speech API 和 Models API(2026-08-25)验证,而非从旧版 OpenAI TTS API 推断:
端点
POST https://openrouter.ai/api/v1/audio/speech返回原始音频字节流。只有非 200 响应才携带 JSON。顶层字段:
model、input、voice、response_format、speed、input_references、provider。response_format为mp3或pcm。API 默认使用pcm,因此此服务器始终显式发送格式。instructions不是顶层字段。它是 OpenAI 提供商选项(provider.options.openai.instructions)。Fish Audio 未记录任何提供商选项,因此对于 Fish 模型会丢弃instructions并在warnings中回报——绝不发送任何虚构字段。speed仅被部分提供商(OpenAI、Azure)支持;在其他地方会被丢弃,而不是在服务端静默忽略。Fish Audio 没有预设声音 id(
alloy/nova/shimmer属于 OpenAI)。将voice留空。声音克隆可用:endpoints API 报告
fish-audio/s2.1-pro-free:free的supports_voice_cloning: true。它是无状态的——你需要在每次请求的input_references中传入 base64 音频样本。没有可创建的持久化voice_id,因此此服务器没有clone_voice工具;请改用render_voiceover上的reference_audio_path。归属头为
HTTP-Referer和X-OpenRouter-Title。
免费模型限制
fish-audio/s2.1-pro-free:free 是免费变体:
20 次请求/分钟,50 次请求/天(账户累计购买 ≥ $10 信用额度后为 1000 次/天)。
可用性、排队和延迟不保证。
当免费模型不可用时,服务器返回明确错误。它绝不切换到付费模型,除非你显式设置
OPENROUTER_VOICE_FALLBACK_MODEL。
瞬时故障(408、429、5xx、网络错误)会以短指数退避重试两次。400/401/403 绝不重试。
测试
.\.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 和 acceptance.py 的实时部分在没有密钥时会干净地跳过。跳过报告为 SKIP,绝不报告为 PASS。
安全
API 密钥存放在
.env(已被 git 忽略)或环境中。它绝不记录日志、绝不写入命令行、绝不通过 MCP 返回。health()和model_info()返回配置,绝不返回凭据。服务器仅使用 stdio,不绑定任何 TCP 端口。
它不执行来自工具输入的任何 shell 命令。FFmpeg/ffprobe 仅在此服务器刚写入的文件上调用,且仅在存在时调用。
文件写入完全按照调用方要求的位置进行(Codex 需要写入任意活动目录),但会拒绝目录、无效的 Windows 文件名和保留设备名,且
overwrite=False时绝不覆盖。
许可证
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.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to synthesize speech via the unlimitedtts API, handling x402 micropayments, spend policy enforcement, and storage of private MP3 results.MIT