elevenlabs-mcp

# ElevenLabs Model Context Protocol (MCP) Server

<div align="center">

[![Discord Community](https://img.shields.io/badge/[email protected]?style=for-the-badge&logo=discord&labelColor=000)](https://discord.gg/elevenlabs)
[![Twitter](https://img.shields.io/badge/[email protected]?style=for-the-badge&logo=twitter&labelColor=000)](https://x.com/ElevenLabsDevs)
[![PyPI](https://img.shields.io/badge/PyPI-elevenlabs--mcp-000000.svg?style=for-the-badge&logo=pypi&labelColor=000)](https://pypi.org/project/elevenlabs-mcp)
[![Tests](https://img.shields.io/badge/tests-passing-000000.svg?style=for-the-badge&logo=github&labelColor=000)](https://github.com/elevenlabs/elevenlabs-mcp-server/actions/workflows/test.yml)

</div>

This repository provides the official ElevenLabs [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol) server, enabling seamless integration of ElevenLabs' powerful Text-to-Speech (TTS) and audio processing APIs with MCP-compatible clients.  This allows applications like [Claude Desktop](https://www.anthropic.com/claude), [Cursor](https://www.cursor.so), [Windsurf](https://codeium.com/windsurf), and [OpenAI Agents](https://github.com/openai/openai-agents-python) to leverage ElevenLabs' capabilities for speech generation, voice cloning, audio transcription, and more.

## Getting Started

This guide provides instructions for setting up the ElevenLabs MCP server with different MCP clients.

### Prerequisites

*   An [ElevenLabs account](https://elevenlabs.io/app/settings/api-keys) with an API key. A free tier is available with 10,000 credits per month.
*   Python 3.7+

### Installation

Install the `elevenlabs-mcp` package using pip:

```bash
pip install elevenlabs-mcp

Configuration for Specific MCP Clients

1. Claude Desktop

This section details how to configure the ElevenLabs MCP server for use with Claude Desktop.

1. Install uv: uv is a fast Python package installer and resolver. Install it using:

   curl -LsSf https://astral.sh/uv/install.sh | sh

   Refer to the uv repository for alternative installation methods.
2. Configure Claude Desktop: Navigate to Claude > Settings > Developer > Edit Config > claude_desktop_config.json and add the following configuration block:

   {
     "mcpServers": {
       "ElevenLabs": {
         "command": "uvx",
         "args": ["elevenlabs-mcp"],
         "env": {
           "ELEVENLABS_API_KEY": "<insert-your-api-key-here>"
         }
       }
     }
   }

   • Replace <insert-your-api-key-here> with your actual ElevenLabs API key.
3. Enable Developer Mode (Windows): If you are using Windows, enable "Developer Mode" in Claude Desktop by clicking "Help" in the hamburger menu (top left) and selecting "Enable Developer Mode".

2. Other MCP Clients (Cursor, Windsurf, etc.)

For other MCP clients, follow these steps:

1. Install the package: (If you haven't already)

   pip install elevenlabs-mcp

2. Get the Configuration: Run the following command to generate the configuration block:

   python -m elevenlabs_mcp --api-key={{PUT_YOUR_API_KEY_HERE}} --print

   • Replace {{PUT_YOUR_API_KEY_HERE}} with your actual ElevenLabs API key.
3. Paste the Configuration: Copy the output from the previous command and paste it into the appropriate configuration directory or file as specified by your MCP client's documentation.

Example Usage with MCP Clients

Once configured, your MCP client can now interact with ElevenLabs. Here are some example prompts you can try:

Important: Using these tools consumes ElevenLabs credits.

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

ELEVENLABS_MCP_BASE_PATH Environment Variable

You can use the ELEVENLABS_MCP_BASE_PATH environment variable to specify the base directory for relative file paths used by the MCP server. This is useful for managing input and output files. Add this variable to the claude_desktop_config.json file (or your client's configuration) as needed.

Contributing

If you'd like to contribute to the project or run the server from source:

1. Clone the repository:

   git clone https://github.com/elevenlabs/elevenlabs-mcp
   cd elevenlabs-mcp

2. Create a virtual environment and install dependencies: We recommend using uv for dependency management.

   uv venv
   source .venv/bin/activate
   uv pip install -e ".[dev]"

3. Configure Environment Variables: Copy the .env.example file to .env and add your ElevenLabs API key:

   cp .env.example .env
   # Edit .env and add your API key

4. Run Tests: Verify that the setup is working correctly by running the tests:

   ./scripts/test.sh
   # Or with options
   ./scripts/test.sh --verbose --fail-fast

5. Install in Claude Desktop (for development):

   mcp install elevenlabs_mcp/server.py

6. Debug with MCP Inspector (for development):

   mcp dev elevenlabs_mcp/server.py

Troubleshooting

Log Locations (Claude Desktop)

Logs for the ElevenLabs MCP server 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 with Certain Tools

Some ElevenLabs API operations (e.g., voice design, audio isolation) can take a significant amount of time. When using the MCP inspector in development mode, you might encounter timeout errors even if the tool completes successfully. This is less likely to occur when using a client like Claude.

"MCP ElevenLabs: spawn uvx ENOENT" Error

This error indicates that the uvx executable cannot be found. To resolve this:

1. Find the Absolute Path: Determine the absolute path to uvx by running the following command in your terminal:

   which uvx

2. Update Configuration: Update the command field in your claude_desktop_config.json (or equivalent) with the absolute path obtained in the previous step. For example:

   {
     "mcpServers": {
       "ElevenLabs": {
         "command": "/usr/local/bin/uvx",  // Example path
         "args": ["elevenlabs-mcp"],
         "env": {
           "ELEVENLABS_API_KEY": "<insert-your-api-key-here>"
         }
       }
     }
   }

   This ensures that the correct executable is being referenced.