OpenRouter Voice MCP

Ein kleiner MCP-Server (Python + FastMCP, stdio), der Text in lokale Audiodateien umwandelt, unter Verwendung von OpenRouter-Sprachmodellen. Standardmodell:

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

Gebaut für vietnamesische Video-Voiceover: Codex oder Claude Code schreibt ein Erzählskript, ruft render_voiceover() auf und erhält einen absoluten Pfad zu einer MP3-Datei, die es direkt an FFmpeg weiterreichen kann.

Codex / Claude Code
        |  MCP stdio
OpenRouter Voice MCP
        |  HTTPS
OpenRouter  ->  fish-audio/s2.1-pro-free:free
        |
    MP3 bytes  ->  local file  ->  FFmpeg / video pipeline

Kein PyTorch, CUDA, lokale Modell-Downloads, lokales LLM oder lokaler HTTP-Port. Nur Python, drei reine Python-Pakete und ein OpenRouter-API-Schlüssel.

Installation

Anforderungen: Python >= 3.10 im PATH, sowie ffmpeg, falls Sie render_long_voiceover() zum Verketten von Segmenten verwenden möchten. Holen Sie sich einen kostenlosen API-Schlüssel unter https://openrouter.ai/keys.

Ein Befehl erledigt alles – venv, Abhängigkeiten, .env, Akzeptanztests und Registrierung sowohl bei Claude Code als auch bei 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

Manuelles Äquivalent, falls Sie jeden Schritt lieber selbst sehen möchten:

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

Auf macOS / Linux gibt es kein install.ps1; verwenden Sie die manuellen Schritte mit python3 -m venv .venv und .venv/bin/python, und registrieren Sie dann wie unten gezeigt.

Bei Claude Code registrieren

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

Bei Codex registrieren

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

Der API-Schlüssel wird aus .env neben server.py gelesen, sodass er niemals in einer Befehlszeile oder in der Konfigurationsdatei eines der CLIs erscheint. Sie können auch OPENROUTER_API_KEY in der Umgebung exportieren – ein exportierter Wert hat Vorrang vor .env.

Related MCP server: MCP MeloTTS Audio Generator

Werkzeuge

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

Gibt zurück:

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

Audiobytes werden auf die Festplatte geschrieben und niemals base64-kodiert über MCP zurückgegeben – der Punkt ist eine echte Datei für FFmpeg.

Konfiguration

Alle Einstellungen sind Umgebungsvariablen (siehe .env.example):

Was die API tatsächlich unterstützt

Verifiziert gegen die Live-OpenRouter-Speech-API und Models-API (2026-08-25), nicht abgeleitet von der älteren OpenAI-TTS-API:

• Endpunkt POST https://openrouter.ai/api/v1/audio/speech gibt einen rohen Audio-Byte-Stream zurück. Nur Nicht-200-Antworten enthalten JSON.

• Top-Level-Felder: model, input, voice, response_format, speed, input_references, provider.

• response_format ist mp3 oder pcm. Die API standardmäßig auf pcm, daher sendet dieser Server das Format immer explizit.

• instructions ist kein Top-Level-Feld. Es ist eine OpenAI-Provider-Option (provider.options.openai.instructions). Fish Audio dokumentiert keine Provider-Optionen, daher wird instructions für Fish-Modelle verworfen und in warnings zurückgemeldet – es werden niemals erfundene Felder gesendet.

• speed wird nur von einigen Providern (OpenAI, Azure) berücksichtigt; es wird anderswo verworfen, anstatt serverseitig stillschweigend ignoriert zu werden.

• Fish Audio hat keine voreingestellten Voice-IDs (alloy / nova / shimmer gehören zu OpenAI). Lassen Sie voice leer.

• Voice-Cloning ist verfügbar: Die Endpoints-API meldet supports_voice_cloning: true für fish-audio/s2.1-pro-free:free. Es ist zustandslos – Sie übergeben bei jeder Anfrage ein Base64-Audiobeispiel in input_references. Es gibt keine persistente voice_id zu erstellen, daher hat dieser Server kein clone_voice-Werkzeug; verwenden Sie stattdessen reference_audio_path bei render_voiceover.

• Attributions-Header sind HTTP-Referer und X-OpenRouter-Title.

Grenzen des kostenlosen Modells

fish-audio/s2.1-pro-free:free ist eine kostenlose Variante:

• 20 Anfragen/Minute, 50 Anfragen/Tag (1000/Tag, sobald ≥ $10 Guthaben auf dem Konto gekauft wurden).

• Verfügbarkeit, Warteschlangen und Latenz sind nicht garantiert.

• Wenn das kostenlose Modell nicht verfügbar ist, gibt der Server einen klaren Fehler zurück. Er wechselt niemals zu einem kostenpflichtigen Modell, es sei denn, Sie setzen explizit OPENROUTER_VOICE_FALLBACK_MODEL.

Vorübergehende Fehler (408, 429, 5xx, Netzwerkfehler) werden zweimal mit kurzem exponentiellem Backoff wiederholt. 400/401/403 werden nie wiederholt.

Tests

.\.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 und die Live-Hälfte von acceptance.py überspringen sauber ohne Schlüssel. Ein Überspringen wird als SKIP gemeldet, niemals als PASS.

Sicherheit

• Der API-Schlüssel befindet sich in .env (git-ignoriert) oder in der Umgebung. Er wird nie protokolliert, nie in eine Befehlszeile geschrieben und nie über MCP zurückgegeben.

• health() und model_info() geben Konfiguration zurück, niemals Anmeldeinformationen.

• Der Server spricht nur stdio und bindet keinen TCP-Port.

• Er führt keine Shell-Befehle aus Werkzeug-Eingaben aus. FFmpeg/ffprobe werden nur auf Dateien aufgerufen, die dieser Server gerade geschrieben hat, und nur, wenn sie vorhanden sind.

• Dateischreibvorgänge gehen genau dorthin, wo der Aufrufer es verlangt (Codex muss in beliebige Kampagnenverzeichnisse schreiben), aber Verzeichnisse, ungültige Windows-Dateinamen und reservierte Gerätenamen werden abgelehnt, und overwrite=False überschreibt nie.

Lizenz

MIT