MCP

このドキュメントは英語の原文から自動翻訳されています。表現に不自然な箇所がある場合があります。正確な内容は英語の原文もあわせてご確認ください。

Supertone TTSをClaude、Cursorなどの MCP 対応クライアントと連携させましょう。Supertone MCPサーバーは、Text-to-Speech APIを組み合わせ可能なModel Context Protocolツール群として公開します。これにより、AIエージェントはボイスの検索、サンプルの試聴、コスト見積もり、ボイスのクローン、音声合成を行い — これらのステップを自ら多段階のワークフローに連結できます。ソース: supertone-inc/supertone-mcp。

できること

音声合成 — ボイス・言語・速度・ピッチ・感情スタイルを制御します。
ボイス検索 — 言語・性別・年齢・ユースケース・スタイルで探し、決定前にサンプルを試聴します。
クローン・管理 — ローカルのオーディオファイルからカスタムボイスを作成・管理します。
使用量の追跡 — クレジット残高と使用履歴を確認します。
オーディオの結合 — 複数のクリップを1つのファイルに結合します（無音ギャップ・クロスフェードのオプション）。

事前準備

uvのインストール（uvxを提供）、またはpipが使えるPython。
Developer Consoleで取得したSupertone API キー。

インストール

どのクライアントも、API キーを環境変数で渡して同じサーバー（uvx supertone-mcp）を実行します。以下からクライアントを選択してください。

Cursor
Claude Desktop
Claude Code
VS Code
Windsurf

~/.cursor/mcp.json（グローバル）または.cursor/mcp.json（プロジェクトごと）に追加し、API キーを入力します:

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

claude_desktop_config.jsonにサーバーを追加し、Claude Desktopを再起動します:

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

設定ファイルの場所:

OS	パス
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

ターミナルから1行で:

claude mcp add supertone-tts -e SUPERTONE_API_KEY=your-api-key-here -- uvx supertone-mcp

すべてのプロジェクトで使うには-s userを追加します。

ワークスペースの.vscode/mcp.jsonに追加します（最上位キーがserversである点に注意）:

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

その後、MCPビューでサーバーを有効化し、Copilot ChatのAgentモードで使用します。

~/.codeium/windsurf/mcp_config.jsonに追加します:

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

WindsurfのCascadeパネルでサーバー一覧を再読み込みします。

環境変数

変数	必須	デフォルト	用途
`SUPERTONE_API_KEY`	はい	—	認証
`SUPERTONE_MCP_VOICE_ID`	いいえ	Aiden（多言語）	`text_to_speech`のデフォルト`voice_id`
`SUPERTONE_OUTPUT_DIR`	いいえ	`~/supertone-tts-output/`	生成されたオーディオファイルの保存先

ツール

サーバーは、エージェントが連結して使える組み合わせ可能なビルディングブロックとして機能を公開します。

音声合成

ツール	説明
`text_to_speech`	速度・ピッチ・感情スタイル・出力形式を制御してオーディオを生成します。
`predict_duration`	生成前に合成の長さとクレジットコストを見積もります。

ボイス検索

ツール	説明
`search_voice`	言語・性別・年齢・ユースケース・スタイルでプリセットボイスを絞り込みます。
`get_voice`	ボイスの詳細情報をすべて取得します。
`preview_voice`	ボイス評価用のサンプルオーディオURLを取得します。

ボイスクローン

ツール	説明
`clone_voice`	ローカルのWAV/MP3（≤ 3 MB）からクローンボイスを作成します。
`search_custom_voice`	作成したクローンボイスを一覧・絞り込みします。
`get_custom_voice`	クローンボイスの詳細を取得します。
`edit_custom_voice`	クローンボイスの名前や説明を更新します。
`delete_custom_voice`	クローンボイスを完全に削除します（元に戻せません）。

使用量とクレジット

ツール	説明
`get_credit_balance`	残りクレジットを確認します。
`get_usage_history`	期間ごとの使用量を表示します。
`get_voice_usage`	特定ボイスの使用量メトリクスを確認します。

オーディオ編集

ツール	説明
`merge_audio_files`	ローカルのオーディオファイル2つ以上を1つに結合します — 単純な連結、無音ギャップ（`gap_ms`）、クロスフェード（`crossfade_ms`）。複数の`text_to_speech`出力をつなぎ合わせるのに便利です。

主な`text_to_speech`パラメータ

text（必須）、voice_id、language、output_format（mp3 / wav）
model — 例: sona_speech_2_flash、sona_speech_1
speed（0.5–2.0）、pitch_shift（−24 〜 +24 半音）、style
output_mode（files / resources / both）、autoplay（デフォルトfalse）、streaming（sona_speech_1のみ）

これらは呼び出しごとのパラメータであるため、エージェントは呼び出しのたびに出力モード・自動再生・モデルを制御します。

主な`merge_audio_files`パラメータ

input_paths（必須） — 順番に並べたローカルオーディオファイル2つ以上。（1つだけ渡すとそのまま返されます。）
gap_ms — クリップ間に挿入する無音の長さ（ミリ秒）。
crossfade_ms — クリップ間のクロスフェードの長さ（ミリ秒）。gap_msと相互排他です。
output_format — 出力形式の上書き。デフォルトは自動判定です：入力の拡張子がすべて同じならその拡張子、混在していればmp3。サンプルレートやチャンネル数が異なっていても、結合前に自動的に正規化されます。

ffmpegはimageio-ffmpegとしてバンドルされているため、システムにffmpegをインストールしなくてもuvx supertone-mcpのまま結合が動作します。

ワークフロー例

検索 → 試聴 → 見積もり → 合成

「落ち着いた韓国語の女性ボイスを見つけてサンプルを聞かせて、コストを確認してから、このアナウンスをmp3で作って。」search_voice() → preview_voice() → predict_duration() + get_credit_balance() → text_to_speech()と連結されます。

クローンしてすぐに使用

「~/recordings/sample.wavからMyVoiceという名前のクローンボイスを作って、そのボイスでこの挨拶を読み上げて再生して。」clone_voice() → get_custom_voice() → text_to_speech(autoplay=true)と連結されます。

スクリプトを分割合成して結合

「このスクリプトの段落をそれぞれ合成して、間に短い無音を入れて1つのmp3にまとめて。」段落ごとのtext_to_speech() → merge_audio_files(gap_ms=...)と連結されます。

トラブルシューティング

クライアントにSupertoneのツールが表示されない

設定ファイルが有効なJSONであること、クライアントを完全に再起動したことを確認してください。ほとんどのクライアントは起動時にのみMCPサーバーを読み込みます。

uvx: command not found

uvxを提供するuvをインストールしてください: uv インストールガイドを参照。またはpip install supertone-mcpの後、commandをsupertone-mcpに設定してください。

認証エラー

SUPERTONE_API_KEYが（シェルではなく）サーバーのenvブロックに設定され、有効であることを確認してください。キーはDeveloper Consoleで取得できます。

生成したオーディオはどこ?

output_mode: filesの場合、オーディオはSUPERTONE_OUTPUT_DIR（デフォルト~/supertone-tts-output/）に保存されます。すぐに再生するにはautoplay: trueを設定してください。

CLI

同じ機能をターミナルとスクリプトから。

カスタムボイス

Supertoneでのボイスクローンの仕組み。

Announcement

できること

事前準備

インストール

環境変数

ツール

主な`text_to_speech`パラメータ

主な`merge_audio_files`パラメータ

ワークフロー例

検索 → 試聴 → 見積もり → 合成

クローンしてすぐに使用

スクリプトを分割合成して結合

トラブルシューティング

関連ドキュメント

CLI

カスタムボイス

​できること

​事前準備

​インストール

​環境変数

​ツール

​主なtext_to_speechパラメータ

​主なmerge_audio_filesパラメータ

​ワークフロー例

検索 → 試聴 → 見積もり → 合成

クローンしてすぐに使用

スクリプトを分割合成して結合

​トラブルシューティング

​関連ドキュメント

CLI

カスタムボイス

できること

事前準備

インストール

環境変数

ツール

主な`text_to_speech`パラメータ

主な`merge_audio_files`パラメータ

ワークフロー例

トラブルシューティング

関連ドキュメント