ElevenLabs MCP Server

A complete Model Context Protocol (MCP) server for ElevenLabs Conversational AI, providing seamless integration with agents, tools, and knowledge base management.

Features

Agent Management: Create, update, delete, and list ElevenLabs conversational AI agents
Tools Integration: Manage webhook and client-side tools for agent functionality
Knowledge Base: Handle document upload, URL scraping, and text-based knowledge sources
RAG Support: Compute and manage Retrieval-Augmented Generation indices
Real-time Updates: Subscribe to resource changes and notifications
Claude Desktop Integration: Easy setup for Claude Desktop users
Cloud Deployment: Docker container ready for remote deployment

Installation

Local Development

Clone the repository:

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

Install dependencies:

pip install -r requirements.txt

Set up environment variables:

cp .env.example .env
# Edit .env with your ElevenLabs API key

Install the package:

pip install -e .

Production Installation

pip install elevenlabs-mcp-server

Configuration

Environment Variables

Create a .env file with the following variables:

ELEVENLABS_API_KEY=your-elevenlabs-api-key-here
ELEVENLABS_BASE_URL=https://api.elevenlabs.io/v1
MCP_SERVER_NAME=elevenlabs-mcp-server
MCP_SERVER_VERSION=1.0.0
REQUEST_TIMEOUT=30
MAX_RETRIES=3
LOG_LEVEL=INFO

Claude Desktop Integration

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "elevenlabs": {
      "command": "python",
      "args": ["-m", "elevenlabs_mcp.server"],
      "env": {
        "ELEVENLABS_API_KEY": "your-elevenlabs-api-key-here"
      }
    }
  }
}

Usage

Starting the Server

# Using the installed command
elevenlabs-mcp-server

# Or using Python module
python -m elevenlabs_mcp.server

Available Tools

Agent Management

create_agent: Create a new conversational AI agent
get_agent: Retrieve agent configuration by ID
list_agents: List all agents with pagination
update_agent: Update existing agent configuration
delete_agent: Delete an agent

Tool Management

create_tool: Create webhook or client-side tools
get_tool: Retrieve tool configuration by ID
list_tools: List all tools with optional filtering
update_tool: Update existing tool configuration
delete_tool: Delete a tool

Knowledge Base Management

create_knowledge_base_from_text: Create knowledge base from text content
create_knowledge_base_from_url: Create knowledge base from URL scraping
get_knowledge_base_document: Retrieve document details
list_knowledge_base_documents: List all knowledge base documents
update_knowledge_base_document: Update document metadata
delete_knowledge_base_document: Delete a document
compute_rag_index: Compute RAG index for enhanced retrieval
get_document_content: Get full document content and chunks

Example Usage

Creating an Agent

{
  "conversation_config": {
    "agent": {
      "language": "en",
      "prompt": {
        "prompt": "You are a helpful customer service agent.",
        "built_in_tools": ["language_detection", "end_call"]
      },
      "first_message": "Hello! How can I help you today?"
    },
    "asr": {
      "quality": "high",
      "provider": "elevenlabs"
    },
    "tts": {
      "model_id": "eleven_turbo_v2",
      "voice_id": "21m00Tcm4TlvDq8ikWAM"
    }
  },
  "name": "Customer Service Agent"
}

Creating a Webhook Tool

{
  "tool_type": "webhook",
  "name": "weather_lookup",
  "description": "Get current weather information",
  "url": "https://api.weather.com/v1/current",
  "method": "GET",
  "parameters": [
    {
      "name": "location",
      "type": "string",
      "description": "City name for weather lookup",
      "required": true
    }
  ]
}

Creating Knowledge Base from Text

{
  "text": "This is important company information about our products...",
  "name": "Company Product Guide",
  "description": "Comprehensive guide to our product offerings"
}

Resources

The server exposes the following MCP resources:

elevenlabs://agents: List all agents
elevenlabs://tools: List all tools
elevenlabs://knowledge-base: List all knowledge base documents

Cloud Deployment

Docker

Build the Docker image:

docker build -t elevenlabs-mcp-server .

Run the container:

docker run -e ELEVENLABS_API_KEY=your-api-key elevenlabs-mcp-server

Docker Compose

version: '3.8'
services:
  elevenlabs-mcp:
    build: .
    environment:
      - ELEVENLABS_API_KEY=your-api-key
      - LOG_LEVEL=INFO
    ports:
      - "8000:8000"
    restart: unless-stopped

Cloud Platforms

Deploy to your preferred cloud platform:

AWS: Use ECS, EKS, or Lambda
Google Cloud: Use Cloud Run, GKE, or Cloud Functions
Azure: Use Container Instances, AKS, or Functions
Heroku: Use container deployment
Railway: Connect your GitHub repository

API Reference

Agent Configuration Schema

{
  "conversation_config": {
    "agent": {
      "language": "en",
      "prompt": {
        "prompt": "System prompt for the agent",
        "tool_ids": ["tool_id_1", "tool_id_2"],
        "built_in_tools": ["language_detection", "end_call"]
      },
      "first_message": "Initial greeting message"
    },
    "asr": {
      "quality": "high",
      "provider": "elevenlabs",
      "user_input_audio_format": "pcm_16000"
    },
    "tts": {
      "model_id": "eleven_turbo_v2",
      "voice_id": "voice_id_here"
    }
  },
  "platform_settings": {
    "evaluation_config": {
      "success_threshold": 0.7
    }
  }
}

Tool Configuration Schema

Webhook Tool

{
  "type": "webhook",
  "name": "tool_name",
  "description": "Tool description",
  "url": "https://api.example.com/endpoint",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer token"
  },
  "parameters": [
    {
      "name": "param_name",
      "type": "string",
      "description": "Parameter description",
      "required": true
    }
  ]
}

Client Tool

{
  "type": "client",
  "name": "tool_name",
  "description": "Tool description",
  "parameters": [
    {
      "name": "param_name",
      "type": "string",
      "description": "Parameter description",
      "required": true
    }
  ],
  "wait_for_response": false
}

Error Handling

The server provides comprehensive error handling with structured error responses:

{
  "error": "Descriptive error message",
  "details": {
    "status_code": 400,
    "error_type": "validation_error"
  }
}

Development

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=elevenlabs_mcp --cov-report=html

Code Quality

# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Lint code
flake8 src/ tests/

# Type checking
mypy src/

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

Documentation: GitHub README
Issues: GitHub Issues
ElevenLabs API: Official Documentation
MCP Protocol: Specification

Changelog

v1.0.0

Initial release
Full agent management support
Tools and knowledge base integration
Claude Desktop configuration
Docker deployment support
Comprehensive error handling
Complete API coverage