elevenlabs-mcp

A full-featured Model Context Protocol (MCP) server for the ElevenLabs 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 and the official elevenlabs SDK (2.x), managed with 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
• An ElevenLabs API key — create one at https://elevenlabs.io/app/settings/api-keys

---

Installation

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

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:

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:

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

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

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

Inspect the tools with the MCP Inspector:

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 © neomorrison