[!WARNING] This local MCP server is deprecated in favor of the ElevenLabs hosted MCP server.
The hosted server is available at
https://api.elevenlabs.io/v1/mcp, with nothing to install or run locally. It authenticates with OAuth, so no API keys are copied into your client. See the hosted MCP server documentation to connect from Claude, Cursor, or any other MCP client.This repository is no longer actively maintained.
Quickstart with Claude Desktop
- Get your API key from ElevenLabs. There is a free tier with 10k credits per month.
- Install
uv(Python package manager), install withcurl -LsSf https://astral.sh/uv/install.sh | shor see theuvrepo for additional install methods. - Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:
{ "mcpServers": { "ElevenLabs": { "command": "uvx", "args": ["elevenlabs-mcp"], "env": { "ELEVENLABS_API_KEY": "<insert-your-api-key-here>" } } } }
If you're using Windows, you will have to enable "Developer Mode" in Claude Desktop to use the MCP server. Click "Help" in the hamburger menu at the top left and select "Enable Developer Mode".
Other MCP clients
For other clients like Cursor and Windsurf, run:
pip install elevenlabs-mcppython -m elevenlabs_mcp --api-key={{PUT_YOUR_API_KEY_HERE}} --printto get the configuration. Paste it into appropriate configuration directory specified by your MCP client.
That's it. Your MCP client can now interact with ElevenLabs through these tools:
Example usage
⚠️ Warning: ElevenLabs credits are needed to use these tools.
Try asking Claude:
- "Create an AI agent that speaks like a film noir detective and can answer questions about classic movies"
- "Generate three voice variations for a wise, ancient dragon character, then I will choose my favorite voice to add to my voice library"
- "Convert this recording of my voice to sound like a medieval knight"
- "Create a soundscape of a thunderstorm in a dense jungle with animals reacting to the weather"
- "Turn this speech into text, identify different speakers, then convert it back using unique voices for each person"
Optional features
File Output Configuration
You can configure how the MCP server handles file outputs using these environment variables in your claude_desktop_config.json:
ELEVENLABS_MCP_BASE_PATH: Specify the base path for file operations (default:~/Desktop). This directory is also the security boundary for input files: any path passed to a tool that reads a local file (e.g.speech_to_text,isolate_audio,speech_to_speech,video_to_music,upload_music_for_inpainting) must resolve inside this directory, whether given as an absolute or relative path. Paths outside it — even if absolute and previously accepted — are rejected. Set this to a directory that contains everything you need to read from or write to.ELEVENLABS_MCP_OUTPUT_MODE: Control how generated files are returned (default:files)
Output Modes
The ELEVENLABS_MCP_OUTPUT_MODE environment variable supports three modes:
-
files(default): Save files to disk and return file pathsjson"env": { "ELEVENLABS_API_KEY": "your-api-key", "ELEVENLABS_MCP_OUTPUT_MODE": "files" } -
resources: Return files as MCP resources; binary data is base64-encoded, text is returned as UTF-8 textjson"env": { "ELEVENLABS_API_KEY": "your-api-key", "ELEVENLABS_MCP_OUTPUT_MODE": "resources" } -
both: Save files to disk AND return as MCP resourcesjson"env": { "ELEVENLABS_API_KEY": "your-api-key", "ELEVENLABS_MCP_OUTPUT_MODE": "both" }
Resource Mode Benefits:
- Files are returned directly in the MCP response as base64-encoded data
- No disk I/O required - useful for containerized or serverless environments
- MCP clients can access file content immediately without file system access
- In
bothmode, resources can be fetched later using theelevenlabs://filenameURI pattern
Use Cases:
files: Traditional file-based workflows, local developmentresources: Cloud environments, MCP clients without file system accessboth: Maximum flexibility, caching, and resource sharing scenarios
Data residency keys
You can specify the data residency region with the ELEVENLABS_API_RESIDENCY environment variable. Defaults to "us".
Note: Data residency is an enterprise only feature. See the docs for more details.
Contributing
If you want to contribute or run from source:
- Clone the repository:
bashgit clone https://github.com/elevenlabs/elevenlabs-mcp cd elevenlabs-mcp
- Create a virtual environment and install dependencies using uv:
bashuv venv source .venv/bin/activate uv pip install -e ".[dev]"
- Copy
.env.exampleto.envand add your ElevenLabs API key:
bashcp .env.example .env # Edit .env and add your API key
- Run the tests to make sure everything is working:
bash./scripts/test.sh # Or with options ./scripts/test.sh --verbose --fail-fast
-
Install the server in Claude Desktop:
mcp install elevenlabs_mcp/server.py -
Debug and test locally with MCP Inspector:
mcp dev elevenlabs_mcp/server.py
Troubleshooting
Logs when running with Claude Desktop can be found at:
- Windows:
%APPDATA%\Claude\logs\mcp-server-elevenlabs.log - macOS:
~/Library/Logs/Claude/mcp-server-elevenlabs.log
Timeouts when using certain tools
Certain ElevenLabs API operations, like voice design and audio isolation, can take a long time to resolve. When using the MCP inspector in dev mode, you might get timeout errors despite the tool completing its intended task.
This shouldn't occur when using a client like Claude.
MCP ElevenLabs: spawn uvx ENOENT
If you encounter the error "MCP ElevenLabs: spawn uvx ENOENT", confirm its absolute path by running this command in your terminal:
bashwhich uvx
Once you obtain the absolute path (e.g., /usr/local/bin/uvx), update your configuration to use that path (e.g., "command": "/usr/local/bin/uvx"). This ensures that the correct executable is referenced.
