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
• Change an audio file to use a different voice

Tools

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

Local audio files

Tools like speech_to_text and voice_change need paths to existing audio files on disk. Pass the full path to each file when prompting your agent. 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.

On hosted MCP (mcp.cartesia.ai), those paths are on the server — use download_url from text_to_speech / download_file instead of a local file_path.

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, voice changer, 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 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.