Cartesia MCP

Cartesia MCP サーバー

Cartesia MCP サーバーは、Cartesia API を Model Context Protocol (MCP) 経由で公開します。これにより、Cursor、Claude Desktop、OpenAI Agents などのクライアントは、単発のスクリプトを使わずに、音声の一覧表示、TTS と STT の実行、発音辞書の管理、音声のクローン作成などを行えます。

ドキュメント： Cartesia docs — MCP

セットアップ

ホステッド（推奨） — https://mcp.cartesia.ai/mcp に接続し、プロンプトが表示されたらサインインします。まだ存在しない場合は、組織用の Cartesia MCP API キーが作成されます。Playground の API Keys から接続することもできます。

Cursor — Cartesia MCP をインストールし、ブラウザーが開いたら Playground にサインインします。

Claude Code：

claude mcp add --transport http --scope user cartesia-mcp https://mcp.cartesia.ai/mcp

/mcp を実行し、cartesia-mcp を選択して、プロンプトが表示されたらサインインします。

または、.cursor/mcp.json／クライアントの MCP 設定に追加します。

{
  "mcpServers": {
    "cartesia-mcp": {
      "url": "https://mcp.cartesia.ai/mcp"
    }
  }
}

ローカル（uvx）

API キーを使って、公開パッケージをお使いのマシンで実行します。uv（uvx により Python 3.13 以降がインストールされます）と Cartesia API キー が必要です。get_credit_usage 用に、任意で 管理者 API キー（Keys → Admin）を設定できます。管理者キーと標準キーは別の認証情報であり、それぞれ対応するルートクラスでのみ使用できます。

CLI — npx add-mcp "uvx cartesia-mcp" --name cartesia --env 'CARTESIA_API_KEY=${CARTESIA_API_KEY}'

Cursor — ローカルの Cartesia MCP をインストールし、Settings → MCP で CARTESIA_API_KEY を設定します。

Claude Code — claude mcp add -e CARTESIA_API_KEY=<your-api-key> cartesia -- uvx cartesia-mcp

{
  "mcpServers": {
    "cartesia": {
      "command": "uvx",
      "args": ["cartesia-mcp"],
      "env": {
        "CARTESIA_API_KEY": "<your-api-key>"
      }
    }
  }
}

試してみる

エージェントに、次のようなことを尋ねてみてください。

• 利用可能な Cartesia 音声をすべて一覧表示する
• 選択した音声（速度、音量、感情）でテキストを音声に変換する
• 音声ファイルをテキストに書き起こす
• 発音辞書を作成し、TTS で使用する
• アカウントのクレジット使用量を確認する
• 既存の音声を別の言語にローカライズする
• カタログのアクセント ID を一覧表示し、クローンした音声にイギリス英語を追加する

ツール

この表は、cartesia_mcp/server.py の @mcp.tool 登録内容と常に同期してください（tests/test_readme_tools.py で検証されます）。変更をリリースする際は、Cartesia docs — MCP にも同じツール名を反映してください。

ツール	説明
text_to_speech	テキストを音声に変換します。省略可能な output_path（ローカルサーバー）、速度、音量、感情、発音辞書を指定できます。デフォルトの save=true では、file_id と24時間有効な download_url が返されます。
speech_to_text	file_id またはサーバーの file_path から音声を書き起こします（デフォルトは mode=batch、または mode=stream）
list_voices	利用可能な音声を一覧表示します（言語、検索、性別などで絞り込めます）
get_voice	IDで音声のメタデータを取得します
clone_voice	file_id またはサーバーの file_path から音声をクローンします
update_voice	クローンした音声の名前または説明を更新します
delete_voice	クローンした音声を削除します
localize_voice	音声を別の言語または方言に適応させます
list_accents	カタログのアクセントIDとメタデータを一覧表示します（british、standard-japanese、…）
list_models	呼び出し可能な Sonic（TTS）および Ink（STT）モデルIDを一覧表示します（`capability=tts
add_voice_accents	カタログのアクセントをインスタント音声クローンに追加します（british、parisian、…）
delete_voice_accent	インスタント音声クローンからカタログのアクセントを削除します
list_pronunciation_dicts	発音辞書を一覧表示します
create_pronunciation_dict	発音辞書を作成します
get_pronunciation_dict	IDで発音辞書を取得します
update_pronunciation_dict	発音辞書を更新します
delete_pronunciation_dict	発音辞書を削除します
download_file	IDでクラウドファイルを取得します（download_url とローカルコピー）
get_credit_usage	期間ごとのクレジット使用量を取得します（CARTESIA_ADMIN_API_KEY）

パラメーターと戻り値の型については、cartesia_mcp/server.py を参照してください。

リリース

バージョンと PyPI への公開は、release-please を介して main 上の Conventional Commits に基づいて実行されます。PR タイトルには feat: … や fix: … のような形式を使用してください（特にスカッシュマージの場合）。CONTRIBUTING.md を参照してください。

ローカル開発

公開済みの uvx cartesia-mcp パッケージではなく、MCP クライアントでチェックアウトしたコードを実行します。

git clone https://github.com/cartesia-ai/cartesia-mcp.git
cd cartesia-mcp
uv sync --dev

CARTESIA_API_KEY（必要に応じて CARTESIA_ADMIN_API_KEY も）を設定します。以下の /path/to/cartesia-mcp をチェックアウトしたコードのパスに置き換えてください。

Cursor — .cursor/mcp.json に追加します。

{
  "mcpServers": {
    "cartesia": {
      "command": "uv",
      "args": ["--directory", "/path/to/cartesia-mcp", "run", "cartesia-mcp"],
      "env": {
        "CARTESIA_API_KEY": "<your-api-key>"
      }
    }
  }
}

Cursor を再起動するか、MCP サーバーを再読み込みしてから、Settings → MCP の下に cartesia が表示されることを確認します。

Claude Code：

claude mcp add -e CARTESIA_API_KEY=<your-api-key> cartesia -- uv --directory /path/to/cartesia-mcp run cartesia-mcp

Claude Code のセッションで /mcp を実行し、cartesia を選択して、ツールが読み込まれることを確認します。

テスト

ユニットテスト（API キー不要）：

uv sync --dev
uv run pytest

すべてのツールのスモークテスト（CARTESIA_API_KEY が必要）：

uv run python scripts/test_all_tools.py

このスクリプトは一時的なクローン済み音声、ローカライズ済み音声、発音辞書を作成し、それらのみを削除します。カタログやその他の既存リソースは削除しません。

詳細設定

出力ディレクトリ

デフォルトでは、生成された音声はサーバーの作業ディレクトリに書き込まれます。固定フォルダーを指定するには、env に OUTPUT_DIRECTORY を追加します。

"env": {
  "CARTESIA_API_KEY": "<your-api-key>",
  "OUTPUT_DIRECTORY": "~/cartesia-output"
}

ローカルサーバー（uvx / stdio）では、text_to_speech に output_path を指定して特定のファイルに書き込むこともできます（たとえば、プロジェクト内の絶対パス）。相対パスは MCP プロセスの作業ディレクトリ（多くの場合、プロジェクトのルートではありません）を基準に解決されるため、絶対パスを使用してください。ホスト型 MCP（mcp.cartesia.ai）では output_path は拒否されます。そこでファイルを取得するには、file_id / download_url を使用してください。

音声入力（file_id または file_path）

speech_to_text と clone_voice には、次のいずれかを指定します。

• file_id — text_to_speech（save=true）または download_file で取得した Cartesia のクラウドファイルです。ホステッド MCP（mcp.cartesia.ai）で使用します。サーバーがデータをダウンロードします。エージェントのマシン上のパスは見つかりません。
• file_path — MCP の実行マシン上に存在する絶対パスです。ローカルの uvx で使用するか、同じホステッドセッション内で先行するツールが返した file_path を渡します。ホステッド MCP では、存在しないパスまたはクライアント側のパスを指定すると、明確な検証エラーが返されます（/Users/... などではなく file_id を使用してください）。

download_url は24時間有効なブラウザー用リンクです。これらのツールへの入力には使用できません。

speech_to_text では、一般的なコンテナー（mp3、flac、wav など）にはデフォルトのバッチモードを使用してください。モノラル PCM WAV または encoding と sample_rate を指定した生の PCM には、mode="stream" を使用してください。

管理者 API キー

一部のツールは、管理者 API キー（sk_car_admin_...）のみを受け付ける管理エンドポイントを呼び出します。CARTESIA_API_KEY と併せて、env に CARTESIA_ADMIN_API_KEY を設定してください。

• CARTESIA_API_KEY — TTS、STT、音声、発音辞書などに使用します。
• CARTESIA_ADMIN_API_KEY — 任意です。現時点では get_credit_usage に必要です。管理者キーは生成ルートでは使用できず、標準キーは管理ルートでは使用できません。

管理者キーは、Playground の Keys → Admin で発行します（組織の管理者のみ）。

ホステッドセッションとレート制限

ホステッド MCP では、ハンドシェイク時のプロトコルバージョンにおいて、クライアントごとに1つのライブセッションが維持されます。initialize の後は、以降のリクエストでレスポンスヘッダー mcp-session-id を再利用してください。このヘッダーを付けずに POST /mcp を送信すると、新しいセッションが開始され、そのクライアントの以前のセッションが置き換えられます。

MCP-Protocol-Version: 2026-07-28 を指定したリクエストでは、セッションは開かれません。以下の新規セッション数制限の対象にはなりません。

30分間リクエストのないセッションは終了します。initialize を再度呼び出して、新しいセッションを開いてください。

新規セッション数は、アクセス・トークンごとに1分あたり5回、クライアント IP ごとに1分あたり15回に制限されています。上限を超えると、サーバーは HTTP 429 を返します。

{
  "error": "too_many_requests",
  "error_description": "MCP session creation rate limit exceeded"
}

Retry-After はウィンドウの秒数（セッション作成時は60）を示します。待機して、まだセッション ID がある場合は同じ ID で再試行してください。429 はログインの有効期限切れではありません。コネクターを失敗と判定したり、新しい OAuth フローを開始したりしないでください。

ホステッド OAuth リダイレクト URI

ホステッド MCP（mcp.cartesia.ai）では、制限付きのリダイレクト URI ポリシーのもとで Dynamic Client Registration を受け付けます。

• カスタムスキーム（デスクトップアプリ）— 例：cursor://…、vscode://…
• ループバック HTTP — http://localhost|127.0.0.1|::1（ポート／パスは任意）
• 許可リスト登録済み HTTPS — Claude、ChatGPT、Cursor web/Agents、VS Code Web のファーストパーティコールバック

コードを変更せずに別の HTTPS コールバックを一時的に許可するには、次を設定します。

MCP_OAUTH_EXTRA_HTTPS_REDIRECTS=partner.example|/mcp/oauth/callback

（host|/path のペアをカンマ区切りで指定）。既知の製品については、コード内でホストを永続的に追加することを推奨します。

API バージョン

すべてのツールは Cartesia-Version を送信します（デフォルトは 2026-08-14。 Cartesia docs に記載されている最新バージョンです）。古い統合日付に固定する場合は、env の CARTESIA_VERSION で上書きしてください。