Cartesia MCP

Cartesia MCP 服务

Cartesia MCP 服务通过 Model Context Protocol (MCP) 提供 Cartesia API，让 Cursor、Claude Desktop 和 OpenAI Agents 等客户端可以列出语音、运行 TTS 和 STT、管理发音词典、克隆语音等，而无需编写一次性脚本。

文档： Cartesia 文档 — 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 密钥。你也可以设置 管理员 API 密钥（Keys → Admin），用于 get_credit_usage。管理员密钥与标准密钥是不同的凭据；每种密钥只能用于对应的路由类别。

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>"
      }
    }
  }
}

试用

可以向你的 Agent 提出以下请求：

• 列出所有可用的 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 发布由 main 分支上的 Conventional Commits 通过 release-please 驱动。请使用 feat: … 或 fix: … 之类的 PR 标题（尤其是在压缩合并时）。请参阅 CONTRIBUTING.md。

本地开发

在 MCP 客户端中运行你的本地检出版本，而不是已发布的 uvx cartesia-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 服务，然后确认 cartesia 显示在 Settings → MCP 下。

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）上使用此项。服务端会下载文件数据。找不到 Agent 机器上的路径。
• file_path — MCP 运行所在机器上的绝对路径，且该路径必须存在。搭配本地 uvx 使用，或传入同一托管会话中较早工具返回的 file_path。在托管 MCP 上，缺失路径或客户端本地路径会返回明确的验证错误（请使用 file_id，而不是 /Users/... 等路径）。

download_url 是有效期为 24 小时的浏览器链接，不能作为这些工具的输入。

对于 speech_to_text，常见容器格式（mp3、flac、wav 等）请使用默认批处理模式。对于单声道 PCM WAV 或原始 PCM，请使用 mode="stream"，并指定 encoding 和 sample_rate。

管理员 API 密钥

部分工具会调用仅接受管理员 API 密钥（sk_car_admin_...）的管理端点。请在 env 中将 CARTESIA_ADMIN_API_KEY 与 CARTESIA_API_KEY 一并设置：

• CARTESIA_API_KEY — 用于 TTS、STT、语音、发音词典等。
• CARTESIA_ADMIN_API_KEY — 可选；目前 get_credit_usage 需要此密钥。管理员密钥不能用于生成路由，标准密钥也不能用于管理路由。

只有组织管理员可以在 Playground 的 Keys → Admin 中创建管理员密钥。

托管会话和速率限制

对于握手时使用的协议版本，托管 MCP 会为每个客户端保持一个活动会话。调用 initialize 后，请在后续请求中复用响应标头中的 mcp-session-id。不带该标头的 POST /mcp 会启动新会话，并替换该客户端之前的会话。

使用 MCP-Protocol-Version: 2026-07-28 的请求不会打开会话，也不计入下方的新会话限制。

会话若 30 分钟没有收到请求就会关闭。请再次调用 initialize 以开启新会话。

每个访问令牌每分钟最多可创建 5 个新会话，每个客户端 IP 每分钟最多可创建 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 策略：

• 自定义协议（桌面应用）— 例如 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 文档中的最新版本）。如果要固定使用较早的集成日期，请在 env 中通过 CARTESIA_VERSION 覆盖。