# elevenlabs-mcp

A full-featured **Model Context Protocol (MCP)** server for the [ElevenLabs](https://elevenlabs.io) API — bring text‑to‑speech, speech‑to‑text, voice cloning, voice design, sound effects, music, audio isolation, dubbing, and account tools directly into **Claude Code** (or any MCP client).

Built in Python with [FastMCP](https://github.com/modelcontextprotocol/python-sdk) and the official [`elevenlabs`](https://pypi.org/project/elevenlabs/) SDK (2.x), managed with [`uv`](https://github.com/astral-sh/uv).

> Audio‑producing tools save their output to a folder on disk (your Desktop by default) and return the file path. Data tools return JSON. Your API key is read from the environment and is never written to the repo.

---

## Features

**28 tools** across the ElevenLabs surface:

| Category | Tools |
| --- | --- |
| 🔊 Speech generation | `text_to_speech`, `text_to_dialogue` (multi‑speaker) |
| 🎚️ Voice transformation | `speech_to_speech` (voice changer) |
| 🎵 Audio generation | `sound_effects`, `compose_music` |
| 🧹 Audio cleanup | `audio_isolation` (remove background noise) |
| 📝 Transcription | `speech_to_text` (Scribe), `forced_alignment` |
| 🧬 Voice design & cloning | `design_voice`, `create_voice_from_preview`, `clone_voice` (instant) |
| 🗂️ Voice management | `list_voices`, `get_voice`, `search_voice_library`, `get_default_voice_settings`, `edit_voice_settings`, `delete_voice` |
| 🧠 Models & account | `list_models`, `get_user_info`, `check_subscription`, `get_usage_stats` |
| 🕓 History | `list_history`, `get_history_item`, `download_history_audio`, `delete_history_item` |
| 🌍 Dubbing | `dub_audio`, `get_dubbing_status`, `download_dubbed_audio` |

---

## Requirements

- **Python 3.10+**
- [**uv**](https://docs.astral.sh/uv/getting-started/installation/)
- An **ElevenLabs API key** — create one at <https://elevenlabs.io/app/settings/api-keys>

---

## Installation

```bash
git clone https://github.com/neomorrison/elevenlabs-mcp.git
cd elevenlabs-mcp
uv sync
```

`uv sync` creates a virtual environment and installs the server plus its dependencies.

### Add to Claude Code

Register the server with the Claude Code CLI. Replace the path with wherever you cloned the repo, and paste your real key:

**Windows (PowerShell):**

```powershell
claude mcp add elevenlabs -s user -e ELEVENLABS_API_KEY=sk_your_key_here -- uv run --directory C:\path\to\elevenlabs-mcp elevenlabs-mcp
```

**macOS / Linux:**

```bash
claude mcp add elevenlabs -s user -e ELEVENLABS_API_KEY=sk_your_key_here -- uv run --directory /path/to/elevenlabs-mcp elevenlabs-mcp
```

Then verify:

```bash
claude mcp list
```

You should see `elevenlabs` listed as **Connected**. Restart Claude Code (or start a new session) and the tools become available.

> `-s user` installs the server for your user across all projects. Use `-s local` (the default) to scope it to the current project, or `-s project` to share it via a checked‑in `.mcp.json`.

### Other MCP clients (Claude Desktop, etc.)

Add this to your client's MCP config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "elevenlabs": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/elevenlabs-mcp", "elevenlabs-mcp"],
      "env": { "ELEVENLABS_API_KEY": "sk_your_key_here" }
    }
  }
}
```

---

## Configuration

Configuration is via environment variables (passed with `-e` in `claude mcp add`, or in a local `.env` for development — see `.env.example`):

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `ELEVENLABS_API_KEY` | ✅ | — | Your ElevenLabs API key. |
| `ELEVENLABS_MCP_OUTPUT_DIR` | | `~/Desktop` | Where generated audio/media files are written. (`ELEVENLABS_MCP_BASE_PATH` is accepted as an alias.) |
| `ELEVENLABS_DEFAULT_VOICE_ID` | | `JBFqnCBsd6RMkjVDRZzb` (George) | Voice used when a tool call omits `voice_id`. |
| `ELEVENLABS_DEFAULT_MODEL_ID` | | `eleven_multilingual_v2` | Default TTS model. |

---

## Usage

Once installed, just ask Claude in natural language. Examples:

- *“Use ElevenLabs to read this paragraph in George's voice and save the mp3.”*
- *“List my ElevenLabs voices.”*
- *“Generate a 10‑second sound effect of rain on a tin roof.”*
- *“Transcribe `C:\\recordings\\interview.wav` with speaker diarization.”*
- *“Design a voice: a calm, wise elderly narrator, then save the second preview.”*
- *“Clone a voice named ‘Studio’ from these three sample files.”*
- *“How many characters do I have left this month?”*
- *“Dub `intro.mp4` into Spanish.”*

Generated files land in your output directory (Desktop by default); each tool returns the absolute path.

---

## Development

```bash
uv sync
# run the server directly over stdio (Ctrl+C to stop)
uv run elevenlabs-mcp
```

Inspect the tools with the MCP Inspector:

```bash
uv run mcp dev src/elevenlabs_mcp/server.py
```

Project layout:

```
src/elevenlabs_mcp/
  __init__.py
  server.py        # FastMCP server + all tools
```

---

## Notes & limitations

- Most audio tools make **paid** ElevenLabs API calls — usage counts against your plan.
- Dubbing is asynchronous: call `dub_audio`, poll `get_dubbing_status` until `status` is `dubbed`, then `download_dubbed_audio`.
- The server never prints to stdout (that channel belongs to the MCP transport); logs go to stderr.

## License

[MIT](LICENSE) © neomorrison