# 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
1. Clone the repository:
```bash
git clone https://github.com/anthropics/elevenlabs-mcp-server.git
cd elevenlabs-mcp-server
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
3. Set up environment variables:
```bash
cp .env.example .env
# Edit .env with your ElevenLabs API key
```
4. Install the package:
```bash
pip install -e .
```
### Production Installation
```bash
pip install elevenlabs-mcp-server
```
## Configuration
### Environment Variables
Create a `.env` file with the following variables:
```env
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`
```json
{
"mcpServers": {
"elevenlabs": {
"command": "python",
"args": ["-m", "elevenlabs_mcp.server"],
"env": {
"ELEVENLABS_API_KEY": "your-elevenlabs-api-key-here"
}
}
}
}
```
## Usage
### Starting the Server
```bash
# 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
```json
{
"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
```json
{
"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
```json
{
"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
1. Build the Docker image:
```bash
docker build -t elevenlabs-mcp-server .
```
2. Run the container:
```bash
docker run -e ELEVENLABS_API_KEY=your-api-key elevenlabs-mcp-server
```
### Docker Compose
```yaml
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
```json
{
"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
```json
{
"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
```json
{
"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:
```json
{
"error": "Descriptive error message",
"details": {
"status_code": 400,
"error_type": "validation_error"
}
}
```
## Development
### Running Tests
```bash
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run tests with coverage
pytest --cov=elevenlabs_mcp --cov-report=html
```
### Code Quality
```bash
# Format code
black src/ tests/
# Sort imports
isort src/ tests/
# Lint code
flake8 src/ tests/
# Type checking
mypy src/
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Support
- Documentation: [GitHub README](https://github.com/anthropics/elevenlabs-mcp-server)
- Issues: [GitHub Issues](https://github.com/anthropics/elevenlabs-mcp-server/issues)
- ElevenLabs API: [Official Documentation](https://docs.elevenlabs.io/)
- MCP Protocol: [Specification](https://modelcontextprotocol.io/)
## 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
