Supertone TTS MCP
About
MCP server for the Supertone TTS API. Generate natural speech, browse and preview the
Details
- Author
- supertone-inc
- Downloads
- 313
- Categories
- Other
Jump to
- Synthesis with text_to_speech and per‑call controls
- Voice discovery via search_voice, get_voice, preview_voice
- Custom voice cloning with full CRUD operations
- Duration and credit prediction without synthesizing
- Usage tracking and credit balance tools
- Streaming and autoplay support
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Supertone TTS MCPCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install with uvx supertone-mcp or pip install supertone-mcp. Set SUPERTONE_API_KEY in your environment, then add the server to your MCP client config (e.g., claude_desktop_config.json). The LLM chains tools like search_voice, preview_voice, predict_duration, and text_to_speech to complete natural‑language requests.
text_to_speech
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.
search_voice
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: ...".
get_voice
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.
get_credit_balance
Returns the remaining Supertone credit balance for the current API key. Use this before long TTS calls to confirm you have enough characters left.
preview_voice
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.
predict_duration
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.
clone_voice
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").
search_custom_voice
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.
edit_custom_voice
Update the name and/or description of an existing custom voice. At least one of name or description must be provided.
delete_custom_voice
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.
get_custom_voice
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.
get_usage_history
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.
get_voice_usage
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.
merge_audio_files
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.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"supertone tts mcp": {
"supertone-tts": {
"command": "uvx",
"args": [
"supertone-mcp"
],
"env": {
"SUPERTONE_API_KEY": "your-api-key-here"
}
}
}
}
}McpServers
{
"supertone-tts": {
"command": "uvx",
"args": [
"supertone-mcp"
],
"env": {
"SUPERTONE_API_KEY": "your-api-key-here"
}
}
}supertone-mcp
<!-- mcp-name: io.github.supertone-inc/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).
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 |
|------------------|----------------------------|------|
| SUPERTONE_MCP_OUTPUT_MODE=files\|resources\|both | text_to_speech(output_mode=...) | Default still files |
| SUPERTONE_MCP_AUTOPLAY=true | text_to_speech(autoplay=...) | Default changed true → false (playback is now explicit) |
| (always streamed) | text_to_speech(streaming=...) | New, default false (one-shot). streaming=true requires model="sona_speech_1" |
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).
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
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
