Cartesia MCP Server

The Cartesia MCP server exposes Cartesia APIs over the Model Context Protocol (MCP) so clients such as Cursor, Claude Desktop, and OpenAI Agents can list voices, run TTS and STT, manage pronunciation dictionaries, clone voices, and more—without one-off scripts.

Documentation: Cartesia docs — MCP

Setup

Hosted (recommended) — connect to https://mcp.cartesia.ai/mcp and sign in when prompted. A Cartesia MCP API key is created for your organization if one does not exist yet. You can also connect from API Keys in the Playground.

Cursor — Install Cartesia MCP, then sign in to the Playground when your browser opens.

Claude Code:

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

Run /mcp, select cartesia-mcp, and sign in when prompted.

Or add to .cursor/mcp.json / your client’s MCP config:

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

Local (uvx)

Run the published package on your machine with an API key. Requires uv (Python 3.13+ is installed by uvx) and a Cartesia API key. Optionally set an admin API key (Keys → Admin) for get_credit_usage. Admin keys and standard keys are separate credentials; each only works on its own route class.

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

Cursor — Install local Cartesia MCP, then set CARTESIA_API_KEY in Settings → MCP.

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

Try it

Ask your agent things like:

• List all available Cartesia voices
• Convert text to audio with a chosen voice (speed, volume, emotion)
• Transcribe an audio file to text
• Create a pronunciation dictionary and use it in TTS
• Check credit usage for your account
• Localize an existing voice into another language
• List catalog accent IDs, then add British English to a cloned voice

Tools

Keep this table in sync with @mcp.tool registrations in cartesia_mcp/server.py (tests/test_readme_tools.py enforces that). Mirror the same tool names on Cartesia docs — MCP when you ship a change.

See cartesia_mcp/server.py for parameters and return types.

Releases

Versions and PyPI publishes are driven by Conventional Commits on main via release-please. Use PR titles like feat: … or fix: … (especially when squash merging). See CONTRIBUTING.md.

Local development

Run your checkout in an MCP client instead of the published uvx cartesia-mcp package:

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

Set CARTESIA_API_KEY (and optionally CARTESIA_ADMIN_API_KEY). Replace /path/to/cartesia-mcp below with your checkout path.

Cursor — add to .cursor/mcp.json:

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

Restart Cursor or reload MCP servers, then confirm cartesia appears under Settings → MCP.

Claude Code:

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

In a Claude Code session, run /mcp, select cartesia, and verify tools load.

Testing

Unit tests (no API keys):

uv sync --dev
uv run pytest

Smoke-test all tools (requires CARTESIA_API_KEY):

uv run python scripts/test_all_tools.py

The script creates temporary cloned/localized voices and pronunciation dictionaries, then deletes only those. It does not delete catalog or other existing resources.

Advanced

Output directory

By default, generated audio is written to the server's working directory. To choose a fixed folder, add OUTPUT_DIRECTORY to env:

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

With the local server (uvx / stdio), text_to_speech also accepts output_path to write a specific file (for example an absolute path under your project). Relative paths resolve against the MCP process working directory (often not your project root), so prefer absolute paths. Hosted MCP (mcp.cartesia.ai) rejects output_path — use file_id / download_url there.

Audio inputs (file_id or file_path)

speech_to_text and clone_voice take one of:

• file_id — a Cartesia cloud file from text_to_speech (save=true) or download_file. Use this on hosted MCP (mcp.cartesia.ai). The server downloads the bytes. A path on the agent machine will not be found.
• file_path — an absolute path on the machine running MCP that must exist. Use this with local uvx, or pass the file_path returned by an earlier tool in the same hosted session. On hosted MCP, a missing or client-local path returns a clear validation error (use file_id instead of /Users/... or similar).

download_url is a 24-hour browser link. It is not an input to those tools.

For speech_to_text, use the default batch mode for common containers (mp3, flac, wav, etc.). Use mode="stream" for mono PCM WAV or raw PCM with encoding and sample_rate.

Admin API key

Some tools call management endpoints that accept admin API keys only (sk_car_admin_...). Set CARTESIA_ADMIN_API_KEY in env alongside CARTESIA_API_KEY:

• CARTESIA_API_KEY — TTS, STT, voices, pronunciation dictionaries, etc.
• CARTESIA_ADMIN_API_KEY — optional; required for get_credit_usage today. Admin keys do not work on generation routes, and standard keys do not work on admin routes.

Mint admin keys in the Playground under Keys → Admin (org admins only).

Hosted sessions and rate limits

Hosted MCP keeps one live session per client on handshake-era protocol versions. After initialize, reuse the mcp-session-id response header on later requests. A POST /mcp without that header starts a new session and replaces the previous one for that client.

Requests with MCP-Protocol-Version: 2026-07-28 do not open a session. They are not counted against the new-session limit below.

A session with no requests for 30 minutes is closed. Call initialize again to open a new one.

New sessions are limited to 5 per minute per access token and 15 per minute per client IP. Over the limit, the server returns HTTP 429:

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

Retry-After is the window in seconds (60 for session creation). Wait and retry with the same session id when you still have one. A 429 is not an expired login — do not mark the connector failed or start a new OAuth flow.

Hosted OAuth redirect URIs

Hosted MCP (mcp.cartesia.ai) accepts Dynamic Client Registration with a restricted redirect-URI policy:

• Custom schemes (desktop apps) — e.g. cursor://…, vscode://…
• Loopback HTTP — http://localhost|127.0.0.1|::1 (any port/path)
• Allowlisted HTTPS — first-party callbacks for Claude, ChatGPT, Cursor web/Agents, and VS Code Web

To temporarily allow another exact HTTPS callback without a code change, set:

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

(comma-separated host|/path pairs). Prefer adding durable hosts in code for known products.

API version

All tools send Cartesia-Version (default 2026-08-14, the latest in Cartesia docs). Override with CARTESIA_VERSION in env if you pin an older integration date.