Skip to main content
Glama

supertone-mcp

CAUTION

⚠️ 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.

supertone-inc/supertone-mcp MCP server

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

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

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

Variable

Required

Default

Description

SUPERTONE_API_KEY

Yes

—

Your Supertone API key

SUPERTONE_MCP_VOICE_ID

No

preset voice (Aiden, multilingual)

Default voice_id for text_to_speech / predict_duration (override per call)

SUPERTONE_OUTPUT_DIR

No

~/supertone-tts-output/

Directory where audio files are saved (used by output_mode=files/both)

Removed in 0.2.0: SUPERTONE_MCP_OUTPUT_MODE and SUPERTONE_MCP_AUTOPLAY — see Migration.

Output modes (text_to_speech output_mode)

Mode

Returns

Use when

files (default)

Plain text with the saved file path + metadata

You want the file on disk

resources

MCP AudioContent + TextContent (no file written)

The client renders audio inline (e.g., Claude.ai chat)

both

File on disk and AudioContent/TextContent

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

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

Tool Parameters

text_to_speech

Parameter

Type

Required

Default

Description

text

string

Yes

—

Text to convert (long text is auto-chunked by the SDK)

voice_id

string

No

env or preset

Voice identifier (browse via search_voice)

language

string

No

ko

Language code — one of 31 (ko, en, ja, …)

output_format

string

No

mp3

mp3 or wav

model

string

No

sona_speech_2_flash

sona_speech_1, sona_speech_2, sona_speech_2_flash, sona_speech_2t, sona_speech_3t, supertonic_api_1, supertonic_api_3

speed

float

No

1.0

0.5–2.0

pitch_shift

int

No

0

-24 to +24 semitones

style

string

No

—

Emotion style (varies by voice)

output_mode

string

No

files

files, resources, or both (see Output modes)

autoplay

bool

No

false

Play the audio locally after synthesis (macOS afplay)

streaming

bool

No

false

Stream synthesis. Only supported by model="sona_speech_1"

include_phonemes

bool

No

false

Return phoneme timing data alongside the audio

normalized_text

string

No

—

Pre-normalized text (only used by sona_speech_2 / sona_speech_2_flash)

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

language

string

e.g., ko, en, ja

gender

string

e.g., male, female

age

string

e.g., young_adult, child

use_case

string

e.g., narration, advertisement

style

string

e.g., neutral, happy

model

string

e.g., sona_speech_2_flash

name

string

partial match

description

string

partial match

get_voice / preview_voice

Tool

Required

Optional

get_voice

voice_id

—

preview_voice

voice_id

language, style, model (filter samples)

clone_voice

Parameter

Type

Required

Description

name

string

Yes

Display name (non-empty)

audio_path

string

Yes

Local WAV or MP3 path (≤3MB). Supports ~ expansion

description

string

No

Optional note

Custom voice CRUD

Tool

Required

Optional

search_custom_voice

—

name, description (partial match)

get_custom_voice

voice_id

—

edit_custom_voice

voice_id

name, description (at least one required)

delete_custom_voice

voice_id

— (IRREVERSIBLE)

Usage & credits

Tool

Required

Optional

get_credit_balance

—

—

get_usage_history

—

— (reports a recent default window)

get_voice_usage

voice_id

—

merge_audio_files

Parameter

Type

Required

Description

input_paths

string[]

Yes

Two or more local mp3/wav paths (~ expansion supported). A single file is returned as-is

gap_ms

int

No

Silence (ms) inserted at each junction. Default 0. Mutually exclusive with crossfade_ms

crossfade_ms

int

No

Crossfade blend (ms) at each junction. Default 0. Mutually exclusive with gap_ms

output_format

string

No

Force mp3 or wav. If omitted: all-same-ext → that ext; mixed → mp3

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

Available Tools

14 tools
clone_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

    A4.2/5.0

    Scored across 14 tools

    Disambiguation5/5

    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).

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Multi-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 PyPI
      MIT