# 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