Supertone MCP

🎙️ supertone-mcp

A composable MCP toolkit for the Supertone TTS API.

Rather than a single "speak this text" command, it exposes Supertone's SDK as a set of building-block tools — synthesis, voice discovery, preview, duration/credit prediction, usage tracking, and full voice-cloning CRUD — that an LLM assembles to fulfill a request. Works in Claude Desktop, Cursor, or any MCP-compatible client.

Covers Korean, English, Japanese, and 31 languages total. Speed (0.5x–2.0x), pitch shift (-24 to +24 semitones), emotion styles, per-call output mode, streaming, and model selection.

✨ Features

🔊 Synthesis

• text_to_speech — Convert text to audio. Per-call control of output_mode (files / resources / both), autoplay, streaming, model, plus include_phonemes / normalized_text. Long text is auto-chunked by the SDK.
• 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).

🧬 Custom Voice Cloning

• clone_voice — Create a cloned voice from a local WAV/MP3 (≤3MB).
• search_custom_voice — List/filter cloned voices.
• get_custom_voice — Full detail for one cloned voice.
• edit_custom_voice — Update name and/or description.
• delete_custom_voice — Permanently delete (irreversible).

🎚️ Audio Assembly

• merge_audio_files — Concatenate two or more local audio files (mp3/wav) into one via a bundled ffmpeg. Supports plain concat, silence gaps between clips (gap_ms), or crossfade blending (crossfade_ms). Output format auto-detected (mixed → mp3) or forced via output_format. No system ffmpeg required.

📊 Usage & Credits

• get_credit_balance — Remaining credits.
• get_usage_history — Usage over a time window.
• get_voice_usage — Usage for a specific voice.

⚠️ Breaking Changes & Migration (0.2.0)

0.2.0 moves behavior control out of environment variables and into per-call tool parameters — so the LLM decides per request, not the server config.

Other changes:

• Default model changed sona_speech_1 → sona_speech_2_flash.
• list_voices was removed (since the discovery release) and replaced by search_voice — call it with no arguments to reproduce the old "list everything" behavior.
• No more hard 300-character limit — longer text is auto-chunked by the SDK (credit/latency scale with length).

💡 Migration tip

If you previously set SUPERTONE_MCP_OUTPUT_MODE or SUPERTONE_MCP_AUTOPLAY, remove them from your client config and pass output_mode / autoplay per call instead. (The server prints a one-time stderr notice if it sees the removed vars.)

🚀 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

Only authentication and stable defaults are configured via the environment — all behavior is controlled per call.

⚠️ Removed in 0.2.0

SUPERTONE_MCP_OUTPUT_MODE and SUPERTONE_MCP_AUTOPLAY — see Migration.

📤 Output Modes (text_to_speech output_mode)

💻 Usage Examples

The MCP client routes natural-language requests across these tools — the value of the toolkit is composition: the LLM chains several tools to satisfy one request.

Example 1 — Discover → Preview → Estimate Cost → Synthesize

"Find a calm Korean female voice, let me hear a sample, check the cost, then make this announcement as an mp3."

The LLM assembles:

search_voice(language="ko", gender="female", style="neutral")   # find candidates
  → preview_voice(voice_id)                                       # sample URLs to confirm the voice
  → predict_duration(text, voice_id) + get_credit_balance()       # gauge cost before spending
  → text_to_speech(text, voice_id, output_format="mp3",
                   output_mode="files")                           # synthesize

Example 2 — Clone My Voice → Use It Right Away

"Make a cloned voice from ~/recordings/sample.wav named MyVoice, then read this greeting with it and play it for me."

The LLM assembles:

clone_voice(name="MyVoice", audio_path="~/recordings/sample.wav")   # create the cloned voice
  → get_custom_voice(voice_id)                                       # confirm it was created
  → text_to_speech(text, voice_id=<cloned>, autoplay=true)           # synthesize, then play immediately

💡 Note

autoplay is a per-call parameter (default false), so playback happens only when explicitly requested.

🧰 Tool Parameters

text_to_speech

predict_duration

Same core parameter schema as text_to_speech (long text auto-chunked). 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

Usage & Credits

merge_audio_files

🛠️ 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