Supertone MCP

🎙️ supertone-mcp

面向 Supertone TTS API 的可组合 MCP 工具包。它不是单一的“朗读这段文本”命令，而是将 Supertone SDK 暴露为一组构建块工具——语音合成、声音发现、试听、时长/额度预测、用量追踪，以及完整的声音克隆 CRUD——由 LLM 组合调用来满足请求。可在 Claude Desktop、Cursor 或任何兼容 MCP 的客户端中使用。

覆盖韩语、英语、日语，共 31 种语言。支持速度（0.5x–2.0x）、音高偏移（-24 到 +24 半音）、情感风格、每次调用的输出模式、流式传输和模型选择。

✨ 主要特性

🗣️ 语音合成

• text_to_speech — 将文本转换为音频。可按调用控制 output_mode（files / resources / both）、autoplay、streaming、model，以及 include_phonemes / normalized_text。长文本由 SDK 自动分块。
• predict_duration — 在不合成的情况下估算音频长度（以及额度消耗）。

🔍 声音发现（预设）

• search_voice — 按语言、性别、年龄、用例、风格、模型、名称或描述筛选目录。
• get_voice — 获取某个声音的完整详情。
• preview_voice — 获取某个声音的示例音频 URL（可按语言/风格/模型筛选）。

🧬 自定义声音克隆

• clone_voice — 从本地 WAV/MP3（≤3MB）创建克隆声音。
• search_custom_voice — 列出/筛选克隆声音。
• get_custom_voice — 获取某个克隆声音的完整详情。
• edit_custom_voice — 更新名称和/或描述。
• delete_custom_voice — 永久删除（不可逆）。

🎧 音频拼接

• merge_audio_files — 通过内置 ffmpeg 将两个或多个本地音频文件（mp3/wav）拼接为一个。支持普通拼接、片段间静音间隔（gap_ms）或交叉淡化混合（crossfade_ms）。输出格式自动检测（混合 → mp3），也可通过 output_format 强制指定。无需系统安装 ffmpeg。

📊 用量与额度

• get_credit_balance — 剩余额度。
• get_usage_history — 指定时间窗口内的用量。
• get_voice_usage — 某个特定声音的用量。

🚀 快速开始

📦 安装

# Using uvx (recommended)
uvx supertone-mcp

# Using pip
pip install supertone-mcp

⚙️ 配置

Claude Desktop

添加到 claude_desktop_config.json：

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

Cursor

添加到你的 Cursor MCP 设置中（JSON 结构与上方相同）。

🔐 环境变量

只有认证和稳定默认值通过环境配置——所有行为均按调用控制。

0.2.0 已移除：SUPERTONE_MCP_OUTPUT_MODE 和 SUPERTONE_MCP_AUTOPLAY — 参见 0.2.0 破坏性变更与迁移。

📤 输出模式（text_to_speech 的 output_mode）

💻 使用示例

MCP 客户端会在这些工具之间路由自然语言请求——工具包的价值在于组合：LLM 会串联多个工具来满足一个请求。

示例 1 — 发现 → 试听 → 估算成本 → 合成

“找一位平静的韩语女声，让我听一个样本，检查成本，然后把这段通知做成 mp3。”

LLM 组合：

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

示例 2 — 克隆我的声音 → 立即使用

“从 ~/recordings/sample.wav 创建一个名为 MyVoice 的克隆声音，然后用它朗读这段问候并播放给我听。”

LLM 组合：

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 是每次调用参数（默认 false），因此只有明确请求时才会播放。

🔄 0.2.0 破坏性变更与迁移

0.2.0 将行为控制从环境变量迁移到每次调用的工具参数——因此由 LLM 按请求决定，而不是服务器配置。

其他变更：

• 默认模型已从 sona_speech_1 改为 sona_speech_2_flash。
• list_voices 已移除（自发现版本起），并由 search_voice 替代——无参数调用它以复现旧的“列出全部”行为。
• 不再有 300 字符硬限制——更长文本由 SDK 自动分块（额度/延迟随长度扩展）。

如果你之前设置过 SUPERTONE_MCP_OUTPUT_MODE 或 SUPERTONE_MCP_AUTOPLAY，请从客户端配置中移除它们，并改为在每次调用时传入 output_mode / autoplay。（如果服务器检测到已移除的变量，会向 stderr 打印一次性通知。）

🔧 工具参数

text_to_speech

predict_duration

与 text_to_speech 具有相同的核心参数结构（长文本自动分块）。返回 "Predicted duration: 2.34s (credit usage is proportional to duration)."。

search_voice

所有参数可选。无筛选 → 完整目录。有任意筛选 → 第一行响应为 Filters applied: ...。

get_voice / preview_voice

clone_voice

自定义声音 CRUD

用量与额度

merge_audio_files

🛠️ 开发

# 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

📄 许可证

MIT