OpenRouter Voice MCP

OpenRouterの音声モデルを使ってテキストをローカル音声ファイルに変換する小さなMCPサーバー（Python + FastMCP、stdio）です。デフォルトモデル：

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、3つの純Pythonパッケージ、そしてOpenRouter APIキーだけです。

インストール

要件：Python >= 3.10 がPATHにあり、さらにrender_long_voiceover()でセグメントを連結する場合はffmpegが必要です。無料のAPIキーはhttps://openrouter.ai/keysで取得できます。

1つのコマンドですべてを実行します：venv、依存関係、.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は生の音声バイトストリームを返します。JSONを返すのは非200応答のみです。

• トップレベルのフィールド：model、input、voice、response_format、speed、input_references、provider。

• response_formatはmp3またはpcmです。**APIはデフォルトでpcm**なので、このサーバーは常にフォーマットを明示的に送信します。

• instructionsはトップレベルのフィールドではありません。これはOpenAIプロバイダーオプション（provider.options.openai.instructions）です。Fish Audioはプロバイダーオプションを文書化していないため、instructionsはFishモデルでは破棄され、warningsで報告されます。発明されたフィールドは送信されません。

• speedは一部のプロバイダー（OpenAI、Azure）でのみ尊重され、他の場所ではサーバー側で静かに無視されるのではなく破棄されます。

• Fish Audioにはプリセットの音声IDがありません（alloy / nova / shimmerはOpenAIのものです）。voiceは空のままにしてください。

• 音声クローンは利用可能です：エンドポイント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は無料バリアントです：

• 1分あたり20リクエスト、1日あたり50リクエスト（アカウントで$10以上のクレジットを購入した場合は1日あたり1000リクエスト）。

• 可用性、キューイング、レイテンシは保証されません。

• 無料モデルが利用できない場合、サーバーは明確なエラーを返します。OPENROUTER_VOICE_FALLBACK_MODELを明示的に設定しない限り、有料モデルに切り替えることは決してありません。

一時的な障害（408、429、5xx、ネットワークエラー）は、短い指数バックオフで2回再試行されます。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ポートをバインドしません。

• ツール入力からシェルコマンドを実行しません。FFmpeg/ffprobeは、このサーバーが書き込んだファイルに対してのみ、存在する場合にのみ呼び出されます。

• ファイルの書き込みは呼び出し元が要求した場所に正確に行われます（Codexは任意のキャンペーンディレクトリに書き込む必要があります）が、ディレクトリ、無効なWindowsファイル名、予約済みデバイス名は拒否され、overwrite=Falseの場合は上書きされません。

ライセンス

MIT