# elevenlabs-mcp

MCP server for the [ElevenLabs](https://elevenlabs.io) text-to-speech API. Provides tools that any MCP-compatible client (Claude Desktop, Claude Code, etc.) can use to generate speech from text.

## Setup

```bash
cd elevenlabs-mcp
npm install
```

Set your API key:

```bash
export ELEVENLABS_API_KEY="your-key-here"
```

Test the server starts correctly:

```bash
node index.js
# Should print "ElevenLabs MCP server running" to stderr
```

## Claude Desktop configuration

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "elevenlabs": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/elevenlabs-mcp/index.js"],
      "env": { "ELEVENLABS_API_KEY": "your-key-here" }
    }
  }
}
```

Replace `/ABSOLUTE/PATH/` with the actual path to this directory.

## Quick-start workflow

1. **Find a voice** — call `list_voices` to get available `voice_id` values
2. **Generate speech** — call `text_to_speech` with the `voice_id` and your text
3. **Check quota** — call `get_quota` to verify character consumption

## Tools

### text_to_speech (primary)

Converts text to an mp3 file. Max 5000 characters per call.

**Params:** `text`, `voice_id`, `output_path`, `model_id`, `stability`, `similarity_boost`, `style`, `language_code`

### text_to_speech_long

For texts over 5000 characters. Splits into chunks and saves numbered files.

**Params:** `text`, `voice_id`, `output_dir`, `base_filename`, `model_id`, `stability`, `similarity_boost`

### list_voices

Lists all voices in your account with `voice_id`, name, category, and preview URL.

### list_models

Lists TTS models with capabilities and language support.

### get_quota

Shows character usage, limit, remaining quota, and next reset date.

## Common voice IDs (reference)

These are default ElevenLabs voices — always verify with `list_voices` as IDs can vary by account:

| Voice | ID |
|---|---|
| Rachel | `21m00Tcm4TlvDq8ikWAM` |
| Bella | `EXAVITQu4vr4xnSDxMaL` |

## Recommended models

| Model | Use case |
|---|---|
| `eleven_multilingual_v2` | Best quality, 32 languages |
| `eleven_flash_v2_5` | Ultra-low latency (~75ms), real-time |
| `eleven_v3` | Newest, most expressive |

## Notes

- Billing is per character consumed
- Use `get_quota` to monitor usage before large jobs
- Character count is logged to stderr on every TTS call
- `text_to_speech_long` splits by paragraph then sentence boundaries