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