ElevenLabs MCP Server

The ElevenLabs MCP tools support several primary audio workflows:

• Text-to-Speech: Generate speech from text using existing voices or specific settings like stability, similarity boost, and style.
• Voice Design & Cloning: Create new voices via text descriptions (age, gender, accent, tone) or by cloning existing voices from audio samples.
• Conversational AI: Create interactive agents with specific personalities, knowledge bases, and custom prompts.
• Audio Processing:
  • Audio Isolation: Separate speech from background noise/music.
  • Voice Conversion: Transform audio to sound like a different character.
  • Transcription: Convert speech to text with speaker identification.
  • Sound Generation: Create sound effects and soundscapes from text descriptions.

To use the ElevenLabs MCP server with Claude Desktop, follow these steps:

1. Obtain an API key from ElevenLabs.
2. Install uv (a Python package manager) using: curl -LsSf https://astral.sh/uv/install.sh | sh.
3. Open your Claude Desktop configuration file at claude_desktop_config.json (accessible via Claude > Settings > Developer > Edit Config).
4. Add the ElevenLabs server configuration to the mcpServers object.

Windows Users: You must enable "Developer Mode" in Claude Desktop (Help > Enable Developer Mode) to use the MCP server.

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

To use the ElevenLabs tools via an MCP client, you must configure your ElevenLabs API key. The tools will not be accessible until the environment variable is correctly set.

1. Obtain an API Key: Get your key from the ElevenLabs Settings page.
2. Configure Environment Variable: Set the key as an environment variable named ELEVENLABS_API_KEY in your MCP client configuration (e.g., in your claude_desktop_config.json or your shell environment).

For clients like Cursor and Windsurf, you can install the package via pip and then generate the necessary configuration by running the server with the --print flag.

1. Install the package: pip install elevenlabs-mcp
2. Generate configuration: python -m elevenlabs_mcp --api-key={{PUT_YOUR_API_KEY_HERE}} --print
3. Copy the output and paste it into your client's specific MCP configuration directory.

The project supports three distinct output_mode settings to control how generated files (like audio) are returned to the MCP client:

1. files: Saves the file to the local filesystem (defaulting to the Desktop) and returns a TextContent message confirming the file path.
2. resources: Does not save to disk; instead, it returns the file as a base64-encoded EmbeddedResource (MCP resource).
3. both: Performs both actions—saves the file to disk and returns it as an EmbeddedResource.

Use handle_output_mode to implement this logic in your tools.

The server provides a resource handler to access files generated by tools (like TTS or STT) using the elevenlabs:// URI scheme.

Usage:

• Use the URI elevenlabs://{filename} to retrieve files.
• For text files, the resource returns text content.
• For binary files (like audio), the resource returns data as a base64 encoded string.

Note: The availability of these resources depends on the ELEVENLABS_MCP_OUTPUT_MODE environment variable (set to files, resources, or both).

The elevenlabs-mcp package provides a CLI utility to automatically generate the claude_desktop_config.json required to use ElevenLabs tools within Claude Desktop.

To use this utility, you must provide an ElevenLabs API key via one of three methods:

1. Use the --api-key CLI argument.
2. Set the ELEVENLABS_API_KEY environment variable.
3. Add ELEVENLABS_API_KEY to a .env file in the current directory.

By default, the utility attempts to locate the Claude configuration directory automatically based on your operating system (Windows, macOS, or Linux).

If you see the error spawn uvx ENOENT, it means the system cannot find the uvx executable. To fix this:

1. Find the absolute path of uvx by running which uvx in your terminal.
2. Update your MCP configuration to use the full absolute path in the command field (e.g., /usr/local/bin/uvx instead of just uvx).

If you encounter issues with the server in Claude Desktop, check the following log locations:

• Windows: %APPDATA%\Claude\logs\mcp-server-elevenlabs.log
• macOS: ~/Library/Logs/Claude/mcp-server-elevenlabs.log

Upload an existing audio file to ElevenLabs to enable inpainting workflows in music_v2. This returns a song_id that can be used in AudioRefChunks or conditioning_ref within a composition plan. You can optionally extract a composition plan from the uploaded audio.

⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs.