# Cartesia MCP Server

[![PyPI version](https://img.shields.io/pypi/v/cartesia-mcp)](https://pypi.org/project/cartesia-mcp/)

The Cartesia MCP server exposes [Cartesia](https://cartesia.ai/) APIs over the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](https://docs.cartesia.ai/tools/ai/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](https://play.cartesia.ai/keys) in the Playground.

**Cursor** — [Install Cartesia MCP](cursor://anysphere.cursor-deeplink/mcp/install?name=cartesia-mcp&config=eyJ1cmwiOiJodHRwczovL21jcC5jYXJ0ZXNpYS5haS9tY3AifQ==), then sign in to the Playground when your browser opens.

**Claude Code:**

```bash
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:

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

### Local (`uvx`)

Run the published package on your machine with an API key. Requires **[uv](https://docs.astral.sh/uv/)** (Python 3.13+ is installed by `uvx`) and a **[Cartesia API key](https://play.cartesia.ai/keys)**. Optionally set an **[admin API key](https://play.cartesia.ai/keys)** (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](cursor://anysphere.cursor-deeplink/mcp/install?name=cartesia&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJjYXJ0ZXNpYS1tY3AiXX0=), then set `CARTESIA_API_KEY` in **Settings → MCP**.

**Claude Code** — `claude mcp add -e CARTESIA_API_KEY=<your-api-key> cartesia -- uvx cartesia-mcp`

```json
{
  "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

| 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 audio from `file_id` or a server `file_path` (`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 `file_id` or a server `file_path` |
| `update_voice` | Update a cloned voice's name or description |
| `delete_voice` | Delete a cloned voice |
| `localize_voice` | Adapt a voice to another language or dialect |
| `list_accents` | List catalog accent IDs and metadata (`british`, `standard-japanese`, …) |
| `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`](./cartesia_mcp/server.py) for parameters and return types.

## Releases

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

## Local development

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

```sh
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`:

```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**:

```bash
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):

```sh
uv sync --dev
uv run pytest
```

Smoke-test all tools (requires `CARTESIA_API_KEY`):

```sh
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`:

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

### 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. Use this with local `uvx`, or pass the `file_path` returned by an earlier tool in the same hosted session.

`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](https://docs.cartesia.ai/api-reference/usage/credits) 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:

```json
{
  "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:

```text
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](https://docs.cartesia.ai/use-the-api/api-conventions)). Override with `CARTESIA_VERSION` in `env` if you pin an older integration date.