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

Requirements

• **uv** — runs the server via uvx with no global install
• Python 3.13+ (installed automatically by uvx)
• A **Cartesia API key** for TTS, STT, voices, and related APIs
• Optionally, an **admin API key** (Keys → Admin) for management tools such as get_credit_usage. Admin keys and standard keys are separate credentials; each only works on its own route class.

Setup

Get an API key. Full instructions: Cartesia docs — MCP.

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

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

Claude Code — claude mcp add -e CARTESIA_API_KEY= cartesia-mcp -- uvx cartesia-mcp

Manual setup

Add to .cursor/mcp.json, .mcp.json (Claude Code), or your client’s MCP config:

{
  "mcpServers": {
    "cartesia-mcp": {
      "command": "uvx",
      "args": ["cartesia-mcp"],
      "env": {
        "CARTESIA_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](./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-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/cartesia-mcp", "run", "cartesia-mcp"],
      "env": {
        "CARTESIA_API_KEY": ""
      }
    }
  }
}

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

Claude Code:

claude mcp add -e CARTESIA_API_KEY= cartesia-mcp -- uv --directory /path/to/cartesia-mcp run cartesia-mcp

In a Claude Code session, run /mcp, select cartesia-mcp, 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": "",
  "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.

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-03-01, the latest in Cartesia docs). Override with CARTESIA_VERSION in env if you pin an older integration date.