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 --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 -- uvx cartesia-mcp`

Manual setup

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

{
  "mcpServers": {
    "cartesia": {
      "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` 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": ""
      }
    }
  }
}

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

Claude Code:

claude mcp add -e CARTESIA_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": "",
  "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-08-14`, the latest in Cartesia docs). Override with `CARTESIA_VERSION` in `env` if you pin an older integration date.