Skip to main content
Glama

HeyGen Voice MCP

An MCP stdio server for the heygen/heygen-voice-1-turbo:free speech model on OpenRouter. It checks the live speech catalog before each request, refuses nonzero pricing or missing model, and never falls back to a paid route. The provider currently returns 44.1 kHz, 16-bit mono PCM; the server wraps it in WAV.

Chinese input is converted to Simplified Chinese by default before synthesis. The original input is not rewritten on disk. Keep user-facing Traditional Chinese or bilingual subtitles as separate text. This conversion is a practical pronunciation measure, not a guarantee of voice quality.

Install and configure

Python 3.11+ is required. From a trusted checkout:

python -m venv .venv
# Windows: .venv\Scripts\python -m pip install .
# macOS / Linux: .venv/bin/python -m pip install .

Set OPENROUTER_API_KEY securely in the server process environment. Never commit keys or supply them in arguments. Example Codex registration (use your actual absolute paths):

codex mcp add heygen-voice -- /absolute/path/to/.venv/bin/heygen-voice-mcp

On Windows, point to .venv\Scripts\heygen-voice-mcp.exe. Restart the MCP host if needed. Environment inheritance depends on the host. Do not expose the key in a client config.

Related MCP server: realtime-tts-mcp

Tools

  • heygen_voice_status: read the current speech catalog; returns the exact model, pricing, available voices, and expiration.

  • heygen_synthesize: provide text, absolute output_path ending in .wav, optional voice (default nadine), and simplify_chinese (default true). The parent directory must exist. Existing files are not overwritten. The tool returns duration, SHA-256 and generation ID, not credentials or audio bytes.

The service receives the input text. Do not transmit private content without authorization. The free endpoint has rate limits and may be retired or unavailable; requests fail closed when the model disappears or pricing is not zero. Never silently substitute a paid model. The live catalog and a :free route are not a provider-enforced spending cap; use OpenRouter account/key limits too.

The tool checks the returned content type and PCM length, not speech accuracy, language, pronunciation, or artistic quality. Verify the actual audio and any transcription separately. gpt-transcribe-mcp is optional and can incur OpenAI API charges; obtain the payer's consent first.

Development

python -m pip install -e .
python -m unittest discover -s tests -v

Tests mock provider calls and do not incur API charges. Live API/model availability, speech intelligibility, and listening are distinct checks; do not claim them from mocked tests.

Sources

MIT licensed. Independent community project, not affiliated with HeyGen or OpenRouter.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers