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 — 1 つのボイスの詳細を取得します。
• preview_voice — ボイスのサンプル音声 URL を取得します(言語/スタイル/モデルでフィルタ可能)。

🧬 カスタムボイスクローニング

• clone_voice — ローカルの WAV/MP3 (≤3MB) からクローン音声を作成します。
• search_custom_voice — クローン音声を一覧表示/フィルタリングします。
• get_custom_voice — 1 つのクローン音声の詳細を取得します。
• edit_custom_voice — 名前や説明を更新します。
• delete_custom_voice — 完全に削除します(取り消し不可)。

🎚️ 音声アセンブリ

• merge_audio_files — 複数のローカル音声ファイル (mp3/wav) を、同梱の ffmpeg で 1 つに連結します。単純な連結、クリップ間の無音ギャップ(gap_ms)、クロスフェードブレンド(crossfade_ms)に対応します。出力フォーマットは自動判別(混在時は → mp3)または output_format で強制指定できます。システムの ffmpeg は不要です。

💳 利用状況とクレジット

• get_credit_balance — 残りのクレジット。
• get_usage_history — 特定期間の利用状況。
• get_voice_usage — 特定のボイスの利用状況。

⚠️ 破壊的変更とマイグレーション (0.2.0)

0.2.0 では、動作の制御が環境変数から呼び出しごとのツールパラメータへ移動しました — サーバー設定ではなく、LLM がリクエストごとに判断します。

その他の変更:

• デフォルトモデルが sona_speech_1 → sona_speech_2_flash に変更されました。
• list_voices は削除されました(discovery リリース以降)。search_voice に置き換えられています — 引数なしで呼び出すと、以前の「すべてを一覧表示」の動作を再現できます。
• 300 文字のハードリミットはなくなりました — 長いテキストは SDK によって自動的に分割されます(クレジット/レイテンシは長さに比例します)。

以前に SUPERTONE_MCP_OUTPUT_MODE や SUPERTONE_MCP_AUTOPLAY を設定していた場合は、クライアント設定からそれらを削除し、代わりに呼び出しごとに output_mode / autoplay を渡してください。(削除された変数を検出した場合、サーバーは一度だけ stderr に通知を出力します。)

🚀 クイックスタート

📦 インストール

# 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 — マイグレーションを参照してください。

📤 出力モード (text_to_speech の output_mode)

💻 使用例

MCP クライアントは自然言語のリクエストをこれらのツールにルーティングします — このツールキットの価値はコンポジションにあります。つまり、LLM が複数のツールを連鎖させて 1 つのリクエストを満たします。

例 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)。そのため、明示的に要求されたときのみ再生されます。

📚 ツールパラメータ

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