supertone-mcp
OfficialThe supertone-mcp server provides a full-featured interface to the Supertone TTS API, enabling speech synthesis, voice management, and custom voice cloning from MCP-compatible clients.
Text-to-Speech Synthesis: Convert text into natural-sounding audio across 23+ languages, with support for speed (0.5x–2.0x), pitch shift (-24 to +24 semitones), emotion styles, and MP3/WAV output. Audio can be saved to disk, returned as MCP resources, or both. Long text is auto-chunked beyond the 300-character limit.
Duration & Cost Prediction: Estimate output audio duration and credit cost before synthesizing, using the same parameters as synthesis.
Voice Catalog Search: Browse and filter Supertone's preset voice catalog by language, gender, age, use case, style, model, name, or description.
Voice Details & Previews: Retrieve full metadata for a specific voice and access sample audio URLs, optionally filtered by language, style, and model.
Credit Balance Check: Monitor the remaining API credit balance for your Supertone API key.
Voice Cloning: Create a custom cloned voice from a local WAV or MP3 file (max 3MB), immediately usable for synthesis.
Custom Voice Management: List/filter cloned voices, update their name or description, or permanently delete them.
supertone-mcp
⚠️ Service Discontinuation Notice
The Supertone API will be permanently shut down on August 31, 2026. After this date, all API requests will stop being served and this package will no longer work.
👉 For the full timeline, refund policy, and details, see the End-of-Life Guide.
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.
Related MCP server: FlowSpeech MCP Server
Features
Synthesis
text_to_speech— Convert text to audio. Per-call control ofoutput_mode(files / resources / both),autoplay,streaming,model, plusinclude_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 viaoutput_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.
Before (env var) | After (per-call parameter) | Note |
|
| Default still |
|
| Default changed |
(always streamed) |
| New, default |
Other changes:
Default model changed
sona_speech_1→sona_speech_2_flash.list_voiceswas removed (since the discovery release) and replaced bysearch_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).
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-mcpConfiguration
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.
Variable | Required | Default | Description |
| Yes | — | Your Supertone API key |
| No | preset voice (Aiden, multilingual) | Default |
| No |
| Directory where audio files are saved (used by |
Removed in 0.2.0:
SUPERTONE_MCP_OUTPUT_MODEandSUPERTONE_MCP_AUTOPLAY— see Migration.
Output modes (text_to_speech output_mode)
Mode | Returns | Use when |
| Plain text with the saved file path + metadata | You want the file on disk |
| MCP | The client renders audio inline (e.g., Claude.ai chat) |
| File on disk and | You want both — preview inline, keep the file |
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") # synthesizeExample 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
autoplayis a per-call parameter (defaultfalse), so playback happens only when explicitly requested.
Tool Parameters
text_to_speech
Parameter | Type | Required | Default | Description |
| string | Yes | — | Text to convert (long text is auto-chunked by the SDK) |
| string | No | env or preset | Voice identifier (browse via |
| string | No |
| Language code — one of 31 ( |
| string | No |
|
|
| string | No |
|
|
| float | No |
| 0.5–2.0 |
| int | No |
| -24 to +24 semitones |
| string | No | — | Emotion style (varies by voice) |
| string | No |
|
|
| bool | No |
| Play the audio locally after synthesis (macOS |
| bool | No |
| Stream synthesis. Only supported by |
| bool | No |
| Return phoneme timing data alongside the audio |
| string | No | — | Pre-normalized text (only used by |
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: ....
Parameter | Type | Description |
| string | e.g., |
| string | e.g., |
| string | e.g., |
| string | e.g., |
| string | e.g., |
| string | e.g., |
| string | partial match |
| string | partial match |
get_voice / preview_voice
Tool | Required | Optional |
|
| — |
|
|
|
clone_voice
Parameter | Type | Required | Description |
| string | Yes | Display name (non-empty) |
| string | Yes | Local WAV or MP3 path (≤3MB). Supports |
| string | No | Optional note |
Custom voice CRUD
Tool | Required | Optional |
| — |
|
|
| — |
|
|
|
|
| — (IRREVERSIBLE) |
Usage & credits
Tool | Required | Optional |
| — | — |
| — | — (reports a recent default window) |
|
| — |
merge_audio_files
Parameter | Type | Required | Description |
| string[] | Yes | Two or more local mp3/wav paths ( |
| int | No | Silence (ms) inserted at each junction. Default |
| int | No | Crossfade blend (ms) at each junction. Default |
| string | No | Force |
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-missingLicense
MIT
Available Tools
14 toolsclone_voiceA
Create a custom voice from a single local audio file. Constraints: WAV or MP3 only, max 3MB, exactly one file. The returned voice_id can be used immediately in text_to_speech. Path supports ~ expansion (e.g., "~/sample.wav").
Inputs: name (required), audio_path (required), description. Returns: result
delete_custom_voiceA
Permanently delete a custom (cloned) voice. THIS IS IRREVERSIBLE — once deleted, the voice cannot be recovered and any saved voice_id referencing it will stop working. Confirm with the user before calling.
Inputs: voice_id (required). Returns: result
edit_custom_voiceA
Update the name and/or description of an existing custom voice. At least one of name or description must be provided.
Inputs: voice_id (required), name, description. Returns: result
get_credit_balanceA
Returns the remaining Supertone credit balance for the current API key. Use this before long TTS calls to confirm you have enough characters left.
Inputs: no named parameters. Returns: result
get_custom_voiceA
Fetch the detail of a single custom (cloned) voice by voice_id. Returns the voice's name and description. Use search_custom_voice to list custom voices and find a voice_id.
Inputs: voice_id (required). Returns: result
get_usage_historyA
Retrieve recent TTS API usage history for the current API key. Returns a plain-text summary broken down by time period, showing the minutes used (and, when available, the voice and model) in each period. Takes no parameters — it reports usage over a recent default window. Use this to review how much synthesis has been consumed.
Inputs: no named parameters. Returns: result
get_voiceA
Fetch full detail for a single voice by voice_id. Returns name, description, age, gender, use_cases, languages, styles, supported models, sample count, and thumbnail URL. Use preview_voice to get the actual sample audio URLs.
Inputs: voice_id (required). Returns: result
get_voice_usageA
Retrieve recent usage for a single voice by voice_id. Returns a plain-text summary of the voice's per-day minutes used over a recent default window. Use search_voice or search_custom_voice to find a voice_id.
Inputs: voice_id (required). Returns: result
merge_audio_filesA
Merge two or more local audio files into a single file using ffmpeg. Supports plain concatenation, silence-gap insertion between clips (gap_ms), or crossfade blending (crossfade_ms). gap_ms and crossfade_ms are mutually exclusive. Output format is auto-detected from the inputs (all-same-ext -> that ext; mixed -> mp3) or overridden via output_format. Use this to stitch multiple text_to_speech outputs into one deliverable.
Inputs: input_paths (required), gap_ms, crossfade_ms, output_format. Returns: result
predict_durationA
Predict the expected output audio duration in seconds for a given text WITHOUT producing any audio file. Accepts the same parameters as text_to_speech. There is no text-length limit: long text is automatically split (auto-chunked), and credit usage and latency scale with the length of the text. Use this to estimate credit cost before synthesizing — credit usage is proportional to the predicted duration.
Inputs: text (required), model, speed, style, +4 more. Returns: result
preview_voiceA
Fetch sample audio URLs for a voice. Optionally filter samples by language, style, and model. Returns one URL per matching sample. v0.2 does NOT play the audio locally; pass the URL to your client to listen.
Inputs: voice_id (required), model, style, language. Returns: result
search_custom_voiceA
List custom (cloned) voices created by this API key. Optional name and description filters perform partial matching. Pagination is handled internally; v0.2 returns the SDK default page.
Inputs: name, description. Returns: result
search_voiceA
Search the Supertone voice catalog. Filters are optional and combined with AND semantics: name, description, language, gender, age, use_case, style, model. With no filters, returns the full catalog (the v0.1 list_voices behavior). The output is a numbered plain-text list; when any filter is set, the first line shows "Filters applied: ...".
Inputs: age, name, model, style, +4 more. Returns: result
text_to_speechA
Generate natural-sounding speech audio from text. Use this when the user wants to: hear text read aloud, create narration or voiceover, generate voice audio, preview how text sounds when spoken, or convert any writing into spoken audio. Supports 31 languages including Korean, English, and Japanese. There is no text-length limit: long text is automatically split (auto-chunked) by the service, and credit usage and latency scale with the length of the text. Set output_mode ('files', 'resources', or 'both') to control how audio is returned, and autoplay=true to play it back on macOS. These per-call parameters REPLACE the removed SUPERTONE_MCP_OUTPUT_MODE and SUPERTONE_MCP_AUTOPLAY environment variables; autoplay now defaults to false. A default voice is already configured -- just call this tool directly. Only call search_voice if the user explicitly asks to change or browse voices.
Inputs: text (required), model, speed, style, +9 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct action or resource: voice cloning, custom voice CRUD, catalog browsing, TTS, duration prediction, audio merging, and usage tracking. No two tools have overlapping purposes; even the get functions are clearly differentiated by domain (custom vs. catalog).
All tools use a consistent snake_case verb_noun pattern (e.g., clone_voice, delete_custom_voice, get_credit_balance). This makes it easy for an agent to infer action and target from the name alone.
With 14 tools, the server covers all core functionalities without being bloated. Each tool serves a necessary role in voice cloning, synthesis, audio manipulation, and account management. The number is well-scoped for the domain.
The tool surface covers the full lifecycle for custom voices (create, read, update, delete, search), catalog exploration, TTS with duration estimation, audio merging, and usage tracking. There are no obvious gaps that would hinder typical workflows.
Maintenance
Related MCP Connectors
Remote text-to-speech MCP server with text_to_speech and list_voices tools. Free plan.
AI voice generation: text-to-speech and voice cloning from any MCP client.
MCP server for Text-to-Speech
MCP server exposing the AceDataCloud Fish Audio API (text-to-speech with voice conditioning)
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that integrates high-quality text-to-speech capabilities with Claude Desktop and other MCP-compatible clients, supporting multiple voice options and audio formats.1MIT
- AlicenseAqualityBmaintenanceA Model Context Protocol server for FlowSpeech text-to-speech. It lets MCP-compatible clients generate human-like audio with context-aware emotion control, pause control, multi-speaker dialogue, and 30+ available voices.627 npmMIT
- AlicenseAqualityDmaintenanceEnables local text-to-speech synthesis for Claude and Cursor using Supertonic 3, with support for multiple voices, expressions, and languages. No API key or cloud required.3MIT
- AlicenseNot gradedqualityDmaintenanceMulti-engine text-to-speech for AI coding assistants. Speaks responses aloud from Claude Code, Cursor, or VS Code via a Claude Code plugin, MCP server, or CLI pipe.85 PyPIMIT