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

API 密钥从 server.py 旁边的 .env 读取，因此它永远不会出现在命令行或任一 CLI 的配置文件中。你也可以在环境中导出 OPENROUTER_API_KEY——导出的值优先于 .env。

Related MCP server: MCP MeloTTS Audio Generator

工具

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）：

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 checklist

smoke_test.py 和 acceptance.py 的实时部分在没有密钥时会干净地跳过。跳过报告为 SKIP，绝不报告为 PASS。

安全

• API 密钥存放在 .env（已被 git 忽略）或环境中。它绝不记录日志、绝不写入命令行、绝不通过 MCP 返回。

• health() 和 model_info() 返回配置，绝不返回凭据。

• 服务器仅使用 stdio，不绑定任何 TCP 端口。

• 它不执行来自工具输入的任何 shell 命令。FFmpeg/ffprobe 仅在此服务器刚写入的文件上调用，且仅在存在时调用。

• 文件写入完全按照调用方要求的位置进行（Codex 需要写入任意活动目录），但会拒绝目录、无效的 Windows 文件名和保留设备名，且 overwrite=False 时绝不覆盖。

许可证

MIT