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과 순수 Python 패키지 3개, 그리고 OpenRouter API 키만 있으면 됩니다.

설치

요구 사항: PATH에 Python >= 3.10, 그리고 render_long_voiceover()로 세그먼트를 연결하려면 ffmpeg가 필요합니다. 무료 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 키는 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가 실제로 지원하는 것

오래된 OpenAI TTS API에서 추론한 것이 아니라, 라이브 OpenRouter Speech API 및 Models API(2026-08-25)에서 검증된 내용입니다:

• 엔드포인트 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는 비워 두세요.

• 음성 복제는 가능합니다: 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 포트를 바인딩하지 않습니다.

• 도구 입력에서 셸 명령을 실행하지 않습니다. FFmpeg/ffprobe는 이 서버가 방금 작성한 파일에 대해서만, 그리고 존재할 때만 호출됩니다.

• 파일 쓰기는 호출자가 요청한 위치에 정확히 수행되지만(Codex는 임의의 캠페인 디렉터리에 써야 함), 디렉터리, 잘못된 Windows 파일 이름, 예약된 장치 이름은 거부되며 overwrite=False는 절대 덮어쓰지 않습니다.

라이선스

MIT