# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Development Commands
### Testing
```bash
# Run tests
pytest
# Run tests with coverage
pytest --cov=elevenlabs_mcp --cov-report=html
# Run specific test file
pytest test_server.py
```
### Code Quality
```bash
# Format code
black src/ tests/
# Sort imports
isort src/ tests/
# Lint code
flake8 src/ tests/
# Type checking
mypy src/
```
### Development Setup
```bash
# Install package in development mode
pip install -e .
# Install with development dependencies
pip install -e ".[dev]"
# Run the MCP server
python -m elevenlabs_mcp.server
# Or use the installed command
elevenlabs-mcp-server
```
## Architecture Overview
This is an **ElevenLabs MCP (Model Context Protocol) Server** that provides integration between Claude Desktop and ElevenLabs Conversational AI APIs.
### Core Components
- **`src/elevenlabs_mcp/server.py`**: Main MCP server using FastMCP framework with tool definitions for:
- Agent management (create, get, list, update, delete)
- Tool management (webhook and client-side tools)
- Knowledge base management (text/URL sources, RAG indices)
- **`src/elevenlabs_mcp/client.py`**: Async HTTP client for ElevenLabs API with error handling and retries
- **`src/elevenlabs_mcp/config.py`**: Configuration management using environment variables
### Key Integration Points
- **MCP Protocol**: Uses FastMCP framework for tool definitions and stdio transport
- **ElevenLabs API**: Async HTTP client with proper authentication (xi-api-key header)
- **Claude Desktop**: Configured via `claude_desktop_config.json` with environment variables
### Project Structure
```
src/elevenlabs_mcp/
├── server.py # Main MCP server with 20+ tools
├── client.py # ElevenLabs API client
├── config.py # Settings and environment configuration
└── __init__.py # Package initialization
```
### Environment Configuration
Required environment variables:
- `ELEVENLABS_API_KEY`: ElevenLabs API key for authentication
- `ELEVENLABS_BASE_URL`: API base URL (default: https://api.elevenlabs.io/v1)
Optional settings:
- `REQUEST_TIMEOUT`: HTTP request timeout (default: 30)
- `MAX_RETRIES`: Maximum API retry attempts (default: 3)
- `LOG_LEVEL`: Logging level (default: INFO)
### Testing Strategy
The codebase includes comprehensive test files:
- Direct API testing (`test_api_direct.py`, `test_api_endpoints.py`)
- MCP server testing (`test_server.py`, `test_mcp_direct.py`)
- Claude Desktop integration testing (`test_claude_desktop_*.py`)
- Configuration testing (`test_fixed_config.py`)
### Deployment Options
- **Local development**: Direct Python module execution
- **Claude Desktop**: MCP server integration via JSON configuration
- **Docker**: Containerized deployment with cloud platform support
- **Cloud platforms**: AWS ECS, Google Cloud Run, Heroku, Railway support
