supertone-mcp

MCP server for Supertone TTS API. Generate high-quality speech, browse the voice catalog, predict synthesis cost, and create cloned voices — directly from Claude Desktop, Cursor, or any MCP-compatible client.

Features

Synthesis

• text_to_speech — Convert text (≤300 chars) to audio. Output as files, MCP resources, or both.

• predict_duration — Estimate audio length (and credit cost) without synthesizing.

Voice discovery (preset)

• search_voice — Filter the catalog by language, gender, age, use_case, style, model, name, or description.

• get_voice — Full detail for one voice.

• preview_voice — Sample audio URLs for a voice (filterable by language/style/model).

• get_credit_balance — Check remaining credits.

Custom voice cloning

• clone_voice — Create a cloned voice from a local WAV/MP3 (≤3MB).

• search_custom_voice — List/filter cloned voices.

• edit_custom_voice — Update name and/or description.

• delete_custom_voice — Permanently delete (irreversible).

Supports Korean, English, Japanese, and 20+ other languages. Speed (0.5x–2.0x), pitch shift (-24 to +24 semitones), and emotion styles.

Breaking change in v0.2: list_voices was removed and replaced by search_voice. To reproduce the old behavior, call search_voice with no arguments.

Installation

# Using uvx (recommended)
uvx supertone-mcp

# Using pip
pip install supertone-mcp

Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "supertone-tts": {
      "command": "uvx",
      "args": ["supertone-mcp"],
      "env": {
        "SUPERTONE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (same JSON shape as above).

Environment Variables

Output modes (text_to_speech)

Usage Examples

Natural language phrasing — the MCP client routes these to the right tool automatically.

Synthesis

"Read this aloud: Hello, how are you today?" "한국어로 '안녕하세요' 천천히 읽어줘"

Estimate before synthesizing

"이 문단 합성하면 몇 초쯤 나와?" → calls predict_duration

Browse / pick a voice

"Find me a female Korean voice for narration" → calls search_voice(language="ko", gender="female", use_case="narration")

"그 중에 첫 번째 목소리 샘플 들어보자" → calls preview_voice(voice_id=...) and returns sample URLs

Check credits

"내 크레딧 얼마 남았어?" → calls get_credit_balance

Clone a voice from a local file

"이 파일로 클론 만들어줘: ~/recordings/sample.wav, 이름은 MyVoice" → calls clone_voice(name="MyVoice", audio_path="~/recordings/sample.wav")

Manage cloned voices

"내가 만든 커스텀 보이스 목록 보여줘" → search_custom_voice "MyVoice 이름을 NarratorA로 바꿔" → edit_custom_voice "MyVoice 삭제해" → delete_custom_voice (prompts for confirmation; irreversible)

Tool Parameters

text_to_speech

predict_duration

Same parameter schema as text_to_speech (no auto-chunking — hard 300-char limit). Returns "Predicted duration: 2.34s (credit usage is proportional to duration).".

search_voice

All parameters optional. With no filters → full catalog. With any filter → first response line is Filters applied: ....

get_voice / preview_voice

clone_voice

Custom voice CRUD

Development

# Clone and install
git clone https://github.com/supertone-inc/supertone-mcp.git
cd supertone-mcp
uv sync

# Run tests
uv run pytest -q

# Run with coverage
uv run pytest --cov=src --cov-report=term-missing

License

MIT