OpenRouter Voice MCP

Un pequeño servidor MCP (Python + FastMCP, stdio) que convierte texto en archivos de audio locales usando modelos de voz de OpenRouter. Modelo por defecto:

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

Diseñado para locución de videos en vietnamita: Codex o Claude Code escribe un guion de narración, llama a render_voiceover() y recibe una ruta absoluta a un MP3 que puede pasar directamente a 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

Sin PyTorch, CUDA, descargas de modelos locales, LLM local ni puerto HTTP local. Solo Python, tres paquetes puramente Python y una clave API de OpenRouter.

Instalación

Requisitos: Python >= 3.10 en PATH, además de ffmpeg si quieres que render_long_voiceover() concatene segmentos. Obtén una clave API gratuita en https://openrouter.ai/keys.

Un solo comando hace todo: venv, dependencias, .env, pruebas de aceptación y registro con Claude Code y 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

Equivalente manual, si prefieres ver cada paso:

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

En macOS / Linux no hay install.ps1; usa los pasos manuales con python3 -m venv .venv y .venv/bin/python, y luego regístrate como se muestra a continuación.

Registro con 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

Registro con 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

La clave API se lee de .env junto a server.py, por lo que nunca aparece en una línea de comandos ni en el archivo de configuración de ninguna CLI. También puedes exportar OPENROUTER_API_KEY en el entorno en su lugar: un valor exportado tiene prioridad sobre .env.

Related MCP server: MCP MeloTTS Audio Generator

Herramientas

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 = "",
)

Devuelve:

{
  "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-..."
}

Los bytes de audio se escriben en disco y nunca se devuelven codificados en base64 a través de MCP: el objetivo es un archivo real para FFmpeg.

Configuración

Todos los ajustes son variables de entorno (ver .env.example):

Lo que la API realmente soporta

Verificado contra la API de voz de OpenRouter y la API de modelos en vivo (2026-08-25), no inferido de la API TTS más antigua de OpenAI:

• El endpoint POST https://openrouter.ai/api/v1/audio/speech devuelve un flujo de bytes de audio crudo. Solo las respuestas que no son 200 llevan JSON.

• Campos de nivel superior: model, input, voice, response_format, speed, input_references, provider.

• response_format es mp3 o pcm. La API usa pcm por defecto, por lo que este servidor siempre envía el formato explícitamente.

• instructions no es un campo de nivel superior. Es una opción de proveedor de OpenAI (provider.options.openai.instructions). Fish Audio no documenta opciones de proveedor, por lo que instructions se descarta para los modelos Fish y se informa en warnings — nunca se envían campos inventados.

• speed solo es respetado por algunos proveedores (OpenAI, Azure); se descarta en otros lugares en lugar de ignorarse silenciosamente en el servidor.

• Fish Audio no tiene IDs de voz predefinidos (alloy / nova / shimmer pertenecen a OpenAI). Deja voice vacío.

• La clonación de voz está disponible: la API de endpoints informa supports_voice_cloning: true para fish-audio/s2.1-pro-free:free. Es sin estado: pasas una muestra de audio en base64 en input_references en cada solicitud. No hay un voice_id persistente que crear, por lo que este servidor no tiene una herramienta clone_voice; usa reference_audio_path en render_voiceover en su lugar.

• Los encabezados de atribución son HTTP-Referer y X-OpenRouter-Title.

Límites del modelo gratuito

fish-audio/s2.1-pro-free:free es una variante gratuita:

• 20 solicitudes/minuto, 50 solicitudes/día (1000/día una vez que se hayan comprado ≥ $10 de crédito en la cuenta).

• La disponibilidad, la cola y la latencia no están garantizadas.

• Cuando el modelo gratuito no está disponible, el servidor devuelve un error claro. Nunca cambia a un modelo de pago a menos que configures explícitamente OPENROUTER_VOICE_FALLBACK_MODEL.

Los fallos transitorios (408, 429, 5xx, errores de red) se reintentan dos veces con una breve retroceso exponencial. 400/401/403 nunca se reintentan.

Pruebas

.\.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 y la mitad en vivo de acceptance.py se omiten limpiamente sin una clave. Una omisión se informa como SKIP, nunca como PASS.

Seguridad

• La clave API vive en .env (ignorado por git) o en el entorno. Nunca se registra, nunca se escribe en una línea de comandos y nunca se devuelve a través de MCP.

• health() y model_info() devuelven configuración, nunca credenciales.

• El servidor solo habla stdio y no vincula ningún puerto TCP.

• No ejecuta comandos de shell desde la entrada de herramientas. FFmpeg/ffprobe se invocan solo en archivos que este servidor acaba de escribir, y solo cuando están presentes.

• Las escrituras de archivos van exactamente donde el llamador pide (Codex necesita escribir en directorios de campaña arbitrarios), pero se rechazan directorios, nombres de archivo de Windows no válidos y nombres de dispositivos reservados, y overwrite=False nunca sobrescribe.

Licencia

MIT