ElevenLabs MCP Enhanced
Provides tools for high-quality text-to-speech synthesis, multi-speaker dialogue generation, voice management and cloning, and comprehensive conversational AI management including transcript retrieval and history analysis.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ElevenLabs MCP Enhanced Generate a [thoughtful] audio clip for this script using the v3 model"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ElevenLabs MCP Enhanced
📑 Table of Contents
Related MCP server: ElevenLabs MCP Server
🚀 What's New in This Fork
This enhanced version adds critical conversational AI features missing from the original:
🤖 AI-Friendly Improvements (v1.0.0)
✅ Official v3 API: Now uses official ElevenLabs endpoints - no proxy needed!
🎯 Smart Voice Defaults:
search_voices()now returns common working voices instantly📚 Educational Error Messages: Errors guide AI agents to success with examples
💡 Clear Tool Guidance: No more confusion about single vs multi-speaker tools
🎤 Accurate v3 Voice IDs: All 20 v3-optimized voices now have correct IDs and descriptions
🏯 Auto-Split Long Dialogues: Automatically splits dialogues over 3000 chars into multiple files
🎯 Auto-Adjust Stability: Invalid stability values auto-round to nearest valid option (0.0, 0.5, 1.0)
🏷️ Smart Tag Simplification: Complex tags auto-convert to valid v3 tags for better quality
⏱️ Dynamic Timeouts: Prevents timeouts on complex dialogues by calculating appropriate wait times
🆕 ElevenLabs v3 Model Support (Official)
🎭 Enhanced Expressiveness: Use the official v3 model with
model="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
🎙️ Conversational AI Features
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
About
This is an enhanced fork of the official ElevenLabs Model Context Protocol (MCP) server that enables interaction with powerful Text to Speech and audio processing APIs. This server allows MCP clients like Claude Desktop, Cursor, Windsurf, OpenAI Agents and others to generate speech, clone voices, transcribe audio, manage conversational AI agents, and now retrieve conversation history.
🚀 Quick Install
Zero Install (Recommended)
No installation required! Just use npx:
npx elevenlabs-mcp-enhanced --api-key YOUR_API_KEYGlobal Install
Install once, use everywhere:
npm install -g elevenlabs-mcp-enhanced
elevenlabs-mcp-enhanced --api-key YOUR_API_KEYEnvironment Variable
Set your API key once:
export ELEVENLABS_API_KEY="your-api-key"
npx elevenlabs-mcp-enhanced📋 Requirements
Node.js 16+ (for npm/npx)
Python 3.11+ (automatically managed by the npm package)
ElevenLabs API Key - Get one at elevenlabs.io
Quickstart with Claude Desktop
Option 1: Using npm/npx (Recommended - No installation required!)
Get your API key from ElevenLabs. There is a free tier with 10k credits per month.
Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:
{
"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 from ElevenLabs.
Install from GitHub:
pip install git+https://github.com/199-biotechnologies/elevenlabs-mcp-enhanced.gitConfigure Claude Desktop with:
{ "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".
Other MCP clients
Using npm/npx:
For other clients like Cursor and Windsurf, you can run the server directly:
npx elevenlabs-mcp-enhanced --api-key YOUR_API_KEYUsing Python:
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"
🆕 v3 Model - Quick Start Guide
🎯 DECISION TREE:
Single speaker? → Use
text_to_speechwithmodel="v3"Multiple speakers? → Use
text_to_dialogue(automatically v3)Need tag examples? → Call
fetch_v3_tags()first
📋 RECOMMENDED WORKFLOW FOR AI:
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 storySingle 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"}
]⚠️ v3 Requirements:
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
🆕 New Conversation Features
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: The get_conversation tool now waits for conversations to complete by default (up to 5 minutes), ensuring you always get the full transcript.
Optional features
You can add the ELEVENLABS_MCP_BASE_PATH environment variable to the claude_desktop_config.json to specify the base path MCP server should look for and output files specified with relative paths.
✅ v3 Model - Now Officially Available!
The v3 model is now officially available through the ElevenLabs API! No proxy or special access needed - just use your regular API key.
What's New:
Official
eleven_v3model IDText-to-dialogue endpoint at
/v1/text-to-dialogue70+ language support
3,000 character limit per request
Enhanced emotional expressiveness
Usage:
Simply set model="v3" in text_to_speech() or use text_to_dialogue() for multi-speaker content. The server now uses the official API endpoints.
Contributing
If you want to contribute or run from source:
Clone the repository:
git clone https://github.com/elevenlabs/elevenlabs-mcp
cd elevenlabs-mcpCreate a virtual environment and install dependencies using 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 keyRun the tests to make sure everything is working:
./scripts/test.sh
# Or with options
./scripts/test.sh --verbose --fail-fastInstall the server in Claude Desktop:
mcp install elevenlabs_mcp/server.pyDebug 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.logmacOS:
~/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:
which uvxOnce 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.
Credits
Enhanced Fork
Boris Djordjevic - Lead Developer
199 Longevity Team - Development and Testing
Original ElevenLabs MCP Server
Jacek Duszenko - jacek@elevenlabs.io
Paul Asjes - paul.asjes@elevenlabs.io
Louis Jordan - louis@elevenlabs.io
Luke Harries - luke@elevenlabs.io
This enhanced fork builds upon the excellent foundation created by the ElevenLabs team, adding critical conversational AI features for improved agent interaction and monitoring.
License
This project maintains the same MIT license as the original ElevenLabs MCP server. See LICENSE for details.
Available Tools
29 toolsadd_knowledge_base_to_agentB
Adds knowledge to agent. Returns: knowledge base ID. Use when: giving agent access to documents or information.
Inputs: agent_id (required), knowledge_base_name (required), url, input_file_path, +1 more.
check_subscriptionA
Checks account subscription. Returns: subscription details and usage. Use when: monitoring API usage and limits.
Inputs: no named parameters.
create_agentB
Creates conversational AI agent. Returns: agent ID and details. Use when: setting up voice-enabled chatbot or assistant.
Inputs: name (required), first_message (required), system_prompt (required), voice_id, +13 more.
create_voice_from_previewB
Saves generated voice to library. Returns: permanent voice ID. Use when: keeping voice from text_to_voice previews.
Inputs: generated_voice_id (required), voice_name (required), voice_description (required).
enhance_dialogueB
Adds audio tags to dialogue. Returns: enhanced text with v3 tags. Use when: improving dialogue with emotions and effects.
Inputs: dialogue_blocks (required).
fetch_v3_tagsA
Lists v3 audio tags. Returns: comprehensive tag list. Use when: preparing text for text_to_speech_v3 or text_to_dialogue with emotions and effects.
Inputs: no named parameters.
get_agentB
Gets agent details. Returns: agent configuration. Use when: viewing specific agent settings and capabilities.
Inputs: agent_id (required).
get_conversationB
Gets conversation with transcript. Returns: conversation details and full transcript. Use when: analyzing completed agent conversations.
Inputs: conversation_id (required), wait_for_completion, include_analysis.
get_conversation_transcriptB
Gets conversation transcript in chunks. Returns: transcript chunk with metadata. Use when: retrieving large conversation transcripts.
Inputs: conversation_id (required), format, chunk, chunk_size.
get_v3_audio_tags_guideA
Gets v3 tag usage guide. Returns: detailed v3 documentation. Use when: learning how to use v3 audio tags effectively.
Inputs: no named parameters.
get_voiceB
Gets voice details. Returns: voice metadata and settings. Use when: need detailed information about a specific voice.
Inputs: voice_id (required).
get_voice_id_by_nameA
Resolves voice name to ID. Returns: JSON with voice_id and confidence. Use when: need voice ID from name with fuzzy matching.
Inputs: voice_name (required).
isolate_audioA
Removes background noise from audio. Returns: cleaned audio file path. Use when: extracting voice from noisy recordings.
Inputs: input_file_path (required), output_directory.
list_agentsB
Lists all agents. Returns: agent list with IDs. Use when: viewing available conversational AI agents.
Inputs: no named parameters.
list_conversationsB
Lists agent conversations. Returns: conversation list with metadata. Use when: browsing conversation history.
Inputs: agent_id, status, limit, offset.
list_modelsA
Lists available TTS models. Returns: model list with capabilities. Use when: choosing between v2, v3, or other models.
Inputs: no named parameters.
list_phone_numbersA
Lists account phone numbers. Returns: phone number list. Use when: viewing available numbers for outbound calls.
Inputs: no named parameters.
make_outbound_callB
Initiates phone call with agent. Returns: call details. Use when: making automated calls via Twilio integration.
Inputs: agent_id (required), agent_phone_number_id (required), to_number (required).
play_audioA
Plays audio file locally. Returns: playback confirmation. Use when: previewing generated audio without downloading.
Inputs: input_file_path (required).
search_voice_libraryB
Searches global voice library. Returns: shared voices list. Use when: finding voices across entire ElevenLabs platform.
Inputs: page, page_size, search.
search_voicesB
Searches available voices. Returns: JSON with voice details. Use when: finding voices by name, gender, or characteristics.
Inputs: search, sort, sort_direction, return_format.
speech_to_speechB
Transforms voice in audio. Returns: audio file with new voice. Use when: changing speaker voice in existing audio.
Inputs: input_file_path (required), voice_name, output_directory.
speech_to_textC
Transcribes audio to text. Returns: transcript text or file path. Use when: converting speech recordings to text.
Inputs: input_file_path (required), language_code, diarize, save_transcript_to_file, +2 more.
text_to_dialogueB
Converts multi-speaker text to audio. Returns: dialogue audio file paths. Use when: creating conversations with multiple voices.
Inputs: inputs (required), output_directory, stability, similarity_boost.
text_to_sound_effectsC
Generates sound effects from text. Returns: audio file path. Use when: creating custom sound effects from descriptions.
Inputs: text (required), duration_seconds, output_directory, output_format.
text_to_speechC
Converts text to speech (v2/v3/flash models). Returns: audio file path. Use when: single speaker narration. Supports v3 with audio tags.
Inputs: text (required), voice_name, output_directory, voice_id, +8 more.
text_to_speech_v3A
Converts text to speech with v3 model and tags. Returns: audio file path. Use when: single speaker needs emotions, pauses, or sound effects.
Inputs: text (required), voice_name, output_directory, voice_id, +2 more.
text_to_voiceA
Creates voice from description. Returns: three voice preview files. Use when: designing custom voice from text prompt.
Inputs: voice_description (required), text, output_directory.
voice_cloneB
Creates voice clone from audio. Returns: new voice ID. Use when: creating custom voice from recordings.
Inputs: name (required), files (required), description.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 29 tools
Most tools have distinct purposes, but there is notable overlap between text_to_speech and text_to_speech_v3, which could cause confusion as both handle single-speaker narration with v3 support mentioned in text_to_speech. Additionally, get_conversation and get_conversation_transcript serve similar functions with minor differences in output format, potentially leading to misselection. However, descriptions help clarify boundaries in most cases.
Tool names follow a consistent snake_case pattern throughout, with clear verb_noun structures (e.g., create_agent, list_models, get_voice). Minor deviations exist, such as text_to_speech_v3 including a version suffix, but this is reasonable for differentiation. Overall, the naming is predictable and readable, supporting easy identification.
With 29 tools, the count is borderline high for the ElevenLabs domain, which covers voice generation, agents, and audio processing. While the scope is broad, some tools might be consolidated (e.g., overlapping speech functions), making it feel slightly heavy. However, it's not extreme and remains manageable for the apparent feature set.
The tool set provides comprehensive coverage for the ElevenLabs domain, including CRUD operations for agents and voices, audio processing (speech-to-text, isolation), generation (text-to-speech, dialogue, sound effects), and utilities (subscription, playback). There are no obvious gaps; agents can handle full workflows from creation to conversation analysis, and voice management includes cloning, searching, and previewing.
Maintenance
Related MCP Connectors
ElevenLabs in natural language: generate speech in any language, create and manage voices, compose m
AI voice generation: text-to-speech and voice cloning from any MCP client.
Manage ElevenLabs voice agents and generate speech, music, sound effects, images, and video.
Audio and video tools for your AI assistant: remove noise, enhance voices, transcribe, and more.
Related MCP Servers
AlicenseBqualityFmaintenanceAn official Model Context Protocol (MCP) server that enables AI clients to interact with ElevenLabs' Text to Speech and audio processing APIs, allowing for speech generation, voice cloning, audio transcription, and other audio-related tasks.271,558MIT- AlicenseNot gradedqualityDmaintenanceOfficial ElevenLabs Model Context Protocol server that enables AI assistants like Claude to interact with Text to Speech and audio processing APIs, allowing them to generate speech, clone voices, transcribe audio, and create soundscapes.1MIT
- AlicenseAqualityDmaintenanceOfficial ElevenLabs MCP server for text-to-speech, voice cloning, audio transcription, and sound generation.24MIT
- AlicenseNot gradedqualityDmaintenanceOfficial MCP server that enables interaction with ElevenLabs Text to Speech and audio processing APIs. It allows generating speech, cloning voices, transcribing audio, and creating sound effects through natural language.MIT