Skip to main content
Glama
README.md
# 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:

```sh
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):

```sh
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.

## 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

```sh
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

- [OpenRouter model](https://openrouter.ai/heygen/heygen-voice-1-turbo:free)
- [OpenRouter text-to-speech API](https://openrouter.ai/docs/guides/overview/multimodal/tts)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)

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