/elevenlabs-mcp-enhanced

Enhanced ElevenLabs MCP server with universal API key support and V3 features

Primary LanguagePythonMIT LicenseMIT

ElevenLabs MCP Enhanced Server

A production-ready Model Context Protocol (MCP) server for ElevenLabs with universal API key support, V3 features, and clean output modes.

✨ Features

  • Universal API Key Support: Works with both xi- and sk- format API keys
  • V3 Audio Features: Full support for audio tags, multi-speaker dialogue, and emotional synthesis
  • Clean Output Mode: Professional, minimal output by default (debug mode available)
  • Comprehensive Testing: 69 test cases covering all functionality
  • Production Ready: Enterprise-grade error handling and reliability

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/bmorphism/elevenlabs-mcp-enhanced.git
cd elevenlabs-mcp-enhanced

# Install dependencies
pip install elevenlabs mcp fastmcp httpx python-dotenv

Configuration

  1. Set your API key:
export ELEVENLABS_API_KEY="your-api-key-here"
  1. Add to Claude MCP:
claude mcp add-json elevenlabs '{"type": "stdio", "command": "python3", "args": ["path/to/server.py"], "env": {"ELEVENLABS_API_KEY": "your-key"}}' --scope user

📝 Usage

Basic Text-to-Speech

from server import text_to_speech

result = text_to_speech("Hello world")
# Output: Audio saved: /path/to/file.mp3 (12345 bytes)

V3 Audio Tags

result = text_to_speech("[excited] Amazing! [whispers] Secret message [normal] Back to normal")

Multi-Speaker Dialogue

dialogue = """
[alice] Hello there!
[bob:excited] Hi Alice, great to see you!
[alice:whispers] I have something to tell you...
"""
result = create_dialogue(dialogue)

🎭 V3 Features

Supported Audio Tags

  • [excited] - Excited delivery
  • [whispers] - Whispering
  • [angry] - Angry tone
  • [sad] - Sad delivery
  • [laughs] - Laughter
  • [sarcastic] - Sarcastic tone
  • [confident] - Confident delivery
  • [normal] - Return to normal

Multi-Speaker Support

  • Named speakers: [alice], [bob], [narrator]
  • Speakers with emotions: [alice:excited], [bob:sad]
  • Character variations: [character_1], [character_2]

⚙️ Configuration Options

Environment Variables

  • ELEVENLABS_API_KEY - Your ElevenLabs API key (required)
  • ELEVENLABS_DEBUG - Set to "true" for verbose output with emojis
  • ELEVENLABS_MCP_BASE_PATH - Custom base path for output files
  • ELEVENLABS_DEFAULT_VOICE_ID - Default voice ID to use

Output Modes

Normal Mode (Default):

Audio saved: /path/to/file.mp3 (37661 bytes)

Debug Mode:

✅ PATCHED TTS Success!
📁 File: /path/to/file.mp3
📊 Size: 37,661 bytes
🔑 API Key: sk_58fe7... (validated)
🎭 Model: eleven_multilingual_v2

🧪 Testing

Run the comprehensive test suite:

python3 tests.py

Test results:

  • 69 total tests across 7 categories
  • 100% pass rate verified
  • Average response time: ~1.4 seconds

📊 API Compatibility

This enhanced server fixes the hardcoded API key format restrictions in the official ElevenLabs MCP server. It accepts:

  • xi- format keys (original format)
  • sk- format keys (new format)
  • Custom format keys (length/pattern validated)

🔧 Available Models

  • eleven_multilingual_v2 - High quality, 29 languages (default)
  • eleven_turbo_v2_5 - Fast generation
  • eleven_flash_v2_5 - Ultra-fast generation

📁 Project Structure

elevenlabs-mcp-enhanced/
├── server.py                    # Main patched server with authentication fix
├── unified_elevenlabs_mcp_server.py  # Unified server with V3 enhancements
├── tests.py                     # Comprehensive test suite (69 tests)
├── requirements.txt             # Python dependencies
└── README.md                    # This file

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

  • Built on top of the official ElevenLabs MCP server
  • Enhanced with V3 features and universal API key support
  • Tested with comprehensive suite of 69 test cases

🐛 Troubleshooting

API Key Issues

The server accepts both xi- and sk- format keys. If you're getting authentication errors:

  1. Verify your API key at https://elevenlabs.io/app/settings/api-keys
  2. Ensure the environment variable is set correctly
  3. Try setting ELEVENLABS_DEBUG=true for detailed error messages

MCP Connection Issues

# Check server status
claude mcp list

# View configuration
claude mcp get elevenlabs

# Remove and re-add if needed
claude mcp remove elevenlabs -s user

Output Issues

  • For cleaner output: Leave ELEVENLABS_DEBUG unset or set to "false"
  • For verbose output: Set ELEVENLABS_DEBUG=true

Version: 1.0.0
Author: @bmorphism
API Key Compatibility: xi- and sk- formats
Test Coverage: 100% (69/69 tests passing)