> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supertoneapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Model Context ProtocolでSupertone TTSをClaude、Cursor、Claude Code、VS Code、Windsurfに接続 — インストール、ツール、トラブルシューティング。

<Note>
  このドキュメントは英語の原文から自動翻訳されています。表現に不自然な箇所がある場合があります。正確な内容は[英語の原文](/en/docs/developer-tools/mcp)もあわせてご確認ください。
</Note>

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

ソース: [supertone-inc/supertone-mcp](https://github.com/supertone-inc/supertone-mcp)。

## できること

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

## 事前準備

* [`uv`](https://docs.astral.sh/uv/)のインストール（`uvx`を提供）、または`pip`が使えるPython。
* [Developer Console](https://console.supertoneapi.com)で取得したSupertone API キー。

## インストール

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

<Tabs>
  <Tab title="Cursor">
    `~/.cursor/mcp.json`（グローバル）または`.cursor/mcp.json`（プロジェクトごと）に追加し、API キーを入力します:

    ```json theme={"dark"}
    {
      "mcpServers": {
        "supertone-tts": {
          "command": "uvx",
          "args": ["supertone-mcp"],
          "env": { "SUPERTONE_API_KEY": "your-api-key-here" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    `claude_desktop_config.json`にサーバーを追加し、Claude Desktopを再起動します:

    ```json theme={"dark"}
    {
      "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`                     |
  </Tab>

  <Tab title="Claude Code">
    ターミナルから1行で:

    ```bash theme={"dark"}
    claude mcp add supertone-tts -e SUPERTONE_API_KEY=your-api-key-here -- uvx supertone-mcp
    ```

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

  <Tab title="VS Code">
    ワークスペースの`.vscode/mcp.json`に追加します（最上位キーが`servers`である点に注意）:

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

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

  <Tab title="Windsurf">
    `~/.codeium/windsurf/mcp_config.json`に追加します:

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

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

## 環境変数

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

## ツール

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

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

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

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

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

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

### 主な`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`のまま結合が動作します。

## ワークフロー例

<CardGroup cols={1}>
  <Card title="検索 → 試聴 → 見積もり → 合成" icon="wand-magic-sparkles">
    *「落ち着いた韓国語の女性ボイスを見つけてサンプルを聞かせて、コストを確認してから、このアナウンスをmp3で作って。」*

    `search_voice()` → `preview_voice()` → `predict_duration()` + `get_credit_balance()` → `text_to_speech()`と連結されます。
  </Card>

  <Card title="クローンしてすぐに使用" icon="clone">
    *「\~/recordings/sample.wavからMyVoiceという名前のクローンボイスを作って、そのボイスでこの挨拶を読み上げて再生して。」*

    `clone_voice()` → `get_custom_voice()` → `text_to_speech(autoplay=true)`と連結されます。
  </Card>

  <Card title="スクリプトを分割合成して結合" icon="layer-group">
    *「このスクリプトの段落をそれぞれ合成して、間に短い無音を入れて1つのmp3にまとめて。」*

    段落ごとの`text_to_speech()` → `merge_audio_files(gap_ms=...)`と連結されます。
  </Card>
</CardGroup>

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

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

  <Accordion title="uvx: command not found">
    `uvx`を提供する`uv`をインストールしてください: [uv インストールガイド](https://docs.astral.sh/uv/getting-started/installation/)を参照。または`pip install supertone-mcp`の後、`command`を`supertone-mcp`に設定してください。
  </Accordion>

  <Accordion title="認証エラー">
    `SUPERTONE_API_KEY`が（シェルではなく）サーバーの`env`ブロックに設定され、有効であることを確認してください。キーは[Developer Console](https://console.supertoneapi.com)で取得できます。
  </Accordion>

  <Accordion title="生成したオーディオはどこ?">
    `output_mode: files`の場合、オーディオは`SUPERTONE_OUTPUT_DIR`（デフォルト`~/supertone-tts-output/`）に保存されます。すぐに再生するには`autoplay: true`を設定してください。
  </Accordion>
</AccordionGroup>

## 関連ドキュメント

<CardGroup cols={2}>
  <Card title="CLI" icon="terminal" href="/ja/docs/developer-tools/cli">
    同じ機能をターミナルとスクリプトから。
  </Card>

  <Card title="カスタムボイス" icon="clone" href="/ja/docs/core-concepts/custom-voices">
    Supertoneでのボイスクローンの仕組み。
  </Card>
</CardGroup>