OpenRouter Voice MCP

Небольшой MCP-сервер (Python + FastMCP, stdio), который превращает текст в локальные аудиофайлы с помощью речевых моделей OpenRouter. Модель по умолчанию:

fish-audio/s2.1-pro-free:free

Создан для озвучки видео на вьетнамском: Codex или Claude Code пишет сценарий повествования, вызывает render_voiceover() и получает абсолютный путь к MP3, который можно сразу передать в 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

Никаких PyTorch, CUDA, локальных загрузок моделей, локальных LLM или локального HTTP-порта. Только Python, три чисто Python-пакета и API-ключ OpenRouter.

Установка

Требования: Python >= 3.10 в PATH, а также ffmpeg, если вы хотите, чтобы render_long_voiceover() объединял сегменты. Получите бесплатный API-ключ на https://openrouter.ai/keys.

Одна команда делает всё — 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 читается из .env рядом с server.py, поэтому он никогда не появляется в командной строке или в конфигурационных файлах обоих 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-..."
}

Аудиобайты записываются на диск и никогда не возвращаются в base64 через MCP — смысл в реальном файле для 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 не документирует опции провайдера, поэтому instructions отбрасывается для моделей Fish и сообщается в warnings — никакие выдуманные поля никогда не отправляются.

• speed поддерживается только некоторыми провайдерами (OpenAI, Azure); в остальных случаях он отбрасывается, а не молча игнорируется на стороне сервера.

• У Fish Audio нет предустановленных идентификаторов голосов (alloy / nova / shimmer принадлежат OpenAI). Оставьте voice пустым.

• Клонирование голоса доступно: API конечных точек сообщает supports_voice_cloning: true для fish-audio/s2.1-pro-free:free. Оно без сохранения состояния — вы передаёте аудиосэмпл в base64 в input_references при каждом запросе. Нет постоянного voice_id для создания, поэтому на этом сервере нет инструмента clone_voice; вместо этого используйте reference_audio_path в render_voiceover.

• Заголовки атрибуции: HTTP-Referer и X-OpenRouter-Title.

Лимиты бесплатной модели

fish-audio/s2.1-pro-free:free — бесплатный вариант:

• 20 запросов в минуту, 50 запросов в день (1000 в день после покупки кредита на сумму ≥ $10 на аккаунте).

• Доступность, очередь и задержка не гарантируются.

• Когда бесплатная модель недоступна, сервер возвращает понятную ошибку. Он никогда не переключается на платную модель, если вы явно не установите 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