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=<your-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": "<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

Tool	Description
`text_to_speech`	Convert text to audio; optional speed, volume, emotion, and pronunciation dict. Default `save=true` returns `file_id` and a 24h `download_url`.
`speech_to_text`	Transcribe an audio file (`mode=batch` default, or `mode=stream`)
`list_voices`	List available voices (filter by language, search, gender, etc.)
`get_voice`	Fetch metadata for a voice by ID
`clone_voice`	Clone a voice from an audio sample
`update_voice`	Update a cloned voice's name or description
`delete_voice`	Delete a cloned voice
`voice_change`	Re-render audio with a different voice
`localize_voice`	Adapt a voice to another language or dialect
`add_voice_accents`	Add catalog accents to an instant voice clone (`british`, `parisian`, …)
`delete_voice_accent`	Remove a catalog accent from an instant voice clone
`list_pronunciation_dicts`	List pronunciation dictionaries
`create_pronunciation_dict`	Create a pronunciation dictionary
`get_pronunciation_dict`	Get a pronunciation dictionary by ID
`update_pronunciation_dict`	Update a pronunciation dictionary
`delete_pronunciation_dict`	Delete a pronunciation dictionary
`download_file`	Fetch a cloud file by ID (`download_url` + local copy)
`get_credit_usage`	Credit usage over time (`CARTESIA_ADMIN_API_KEY`)

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.

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.

Metadata

Release files for cartesia-mcp 0.22.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cartesia-mcp 0.22.2
File	Size	Uploaded
cartesia_mcp-0.22.2.tar.gz	70.5 kB	Sep 21, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cartesia-mcp 0.22.2
File	Interpreter	ABI	Platform	Reset
cartesia_mcp-0.22.2-py3-none-any.whl 55.1 kB Sep 21, 2026	Python 3	none	any	Details

Total release size: 125.6 kB

Release files / cartesia_mcp-0.22.2.tar.gz

Download URL	cartesia_mcp-0.22.2.tar.gz
Size	70.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`a59e91739b61e0228b1419d4d686d8547d6e3a1dbd8555a104fe0e507466bef7`
BLAKE2b-256 checksum How to use checksums	`23aa5af8636bc4ae8cec219de23fae92ff5046662487e5149aff7a6dde6c6381`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / cartesia_mcp-0.22.2-py3-none-any.whl

Download URL	cartesia_mcp-0.22.2-py3-none-any.whl
Size	55.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`84a3e33f47edeaed3dcc385b80073cb2e8438a2e3eef896a75816be5320eb24a`
BLAKE2b-256 checksum How to use checksums	`dd6989c1cce5650da3e9c7718aaab80b43cd36a439a2081c0fdd5411edcf34b1`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`