ElevenLabs MCP Enhanced

Enhanced fork of the official ElevenLabs MCP serverwith additional conversational AI features including conversation history and transcript retrieval.

This enhanced version is developed and maintained byBoris Djordjevicand the199 Longevityteam.

- 🚀 What's New
- 🚀 Quick Install
- 📋 Requirements
- ⚙️ Setup Guide
- 💡 Example Usage
- 🛠️ Development
- 👥 Credits

- 🎭 Enhanced Expressiveness: Use the official v3 model withmodel="v3"parameter
- 🎤 Audio Tags: Add emotions and sound effects like[thoughtful],[crying],[laughing],[piano]
- 👥 Multi-Speaker Dialogue: Generate natural conversations between multiple speakers
- ✨ Dialogue Enhancement: Automatically enhance your dialogue with proper formatting and tags
- 🌍 70+ Languages: v3 supports multilingual synthesis with emotional control
- ✅ Official API: Now uses the official ElevenLabs text-to-dialogue endpoint

- Conversation History: Retrieve full conversation details including transcripts
- 📝 Transcript Access: Get conversation transcripts in multiple formats (plain, timestamps, JSON)
- ⏳ Real-time Monitoring: Wait for ongoing conversations to complete and retrieve results
- 🔍 Conversation Search: List and filter conversations by agent, status, and more
- 🎨 Improved Formatting: Consistent formatting across all list operations

This is an enhanced fork of the official ElevenLabsModel Context Protocol (MCP)server that enables interaction with powerful Text to Speech and audio processing APIs. This server allows MCP clients likeClaude Desktop,Cursor,Windsurf,OpenAI Agentsand others to generate speech, clone voices, transcribe audio, manage conversational AI agents, and now retrieve conversation history.

npx elevenlabs-mcp-enhanced --api-key YOUR_API_KEY

npm install -g elevenlabs-mcp-enhanced elevenlabs-mcp-enhanced --api-key YOUR_API_KEY

export ELEVENLABS_API_KEY="your-api-key" npx elevenlabs-mcp-enhanced

- Node.js 16+(for npm/npx)
- Python 3.11+(automatically managed by the npm package)
- ElevenLabs API Key- Get one atelevenlabs.io

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

That's it! No installation needed - npx will automatically download and run the server.

Option 2: Using Python (Original method)

If you prefer the original Python installation:
- Get your API key fromElevenLabs.
- Install from GitHub:

pip install git+https://github.com/199-biotechnologies/elevenlabs-mcp-enhanced.git

{ "mcpServers": { "ElevenLabs": { "command": "python", "args": ["-m", "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".

For other clients like Cursor and Windsurf, you can run the server directly:

npx elevenlabs-mcp-enhanced --api-key YOUR_API_KEY

- pip install elevenlabs-mcp
- python -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:

⚠️ Warning: ElevenLabs credits are needed to use these tools.

- "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"
- Single speaker?→ Usetext_to_speechwithmodel="v3"
- Multiple speakers?→ Usetext_to_dialogue(automatically v3)
- Need tag examples?→ Callfetch_v3_tags()first

1. User: "Create an emotional story with sound effects" 2. AI: fetch_v3_tags() → Gets list of available tags 3. AI: search_voices("v3") → Gets v3-optimized voices 4. AI: text_to_dialogue(...) → Creates the story

Single Speaker Examples (text_to_speech):

- "Generate: '[thoughtful] The universe is vast... [piano] ...and full of mysteries.'"
- "Create narration with: '[whispering] Secret message [footsteps] [door creaking]'"

Multi-Speaker Examples (text_to_dialogue - ALWAYS v3):

# Simple conversation inputs = [ {"text": "How are you?", "voice_name": "James"}, {"text": "I'm great!", "voice_name": "Jane"} ] # With emotion tags inputs = [ {"text": "[excited] I found treasure!", "voice_name": "James"}, {"text": "[skeptical] Really? [pause] Where?", "voice_name": "Jane"} ]

- Stability: MUST be 0.0, 0.5, or 1.0 (no other values!)
- Best voices: James, Jane, Sarah, Mark, etc. (search "v3" to find them)
- Always check fetch_v3_tags() for available audio tags

With the enhanced conversation tools, you can now:

- "Get the conversation transcript from conversation ID abc123" (automatically waits for completion)
- "List all conversations from my agent and show me the completed ones"
- "Get conversation xyz789 immediately without waiting" (set wait_for_completion=false)
- "Show me all conversations in JSON format with timestamps"
- "Get the conversation history including analysis data"

Note:Theget_conversationtool now waits for conversations to complete by default (up to 5 minutes), ensuring you always get the full transcript.

You can add theELEVENLABS_MCP_BASE_PATHenvironment variable to theclaude_desktop_config.jsonto specify the base path MCP server should look for and output files specified with relative paths.

The v3 model is now officially available through the ElevenLabs API! No proxy or special access needed - just use your regular API key.

- Officialeleven_v3model ID
- Text-to-dialogue endpoint at/v1/text-to-dialogue
- 70+ language support
- 3,000 character limit per request
- Enhanced emotional expressiveness

Usage:Simply setmodel="v3"intext_to_speech()or usetext_to_dialogue()for multi-speaker content. The server now uses the official API endpoints.

If you want to contribute or run from source:

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

- Create a virtual environment and install dependenciesusing uv:

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

- Copy.env.exampleto.envand add your ElevenLabs API key:

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

- Run the tests to make sure everything is working:

./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

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

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.

If you encounter the error "MCP ElevenLabs: spawn uvx ENOENT", confirm its absolute path by running this command in your terminal:

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.

- Boris Djordjevic- Lead Developer
- 199 Longevity Team- Development and Testing

- Jacek Duszenko-jacek@elevenlabs.io
- Paul Asjes-paul.asjes@elevenlabs.io
- Louis Jordan-louis@elevenlabs.io
- Luke Harries-luke@elevenlabs.io

This project maintains the same MIT license as the original ElevenLabs MCP server. SeeLICENSEfor details.

A text-to-speech server for VOICEROID2 via the voiceroid_daemon.