elevenlabs-mcp-agents: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Testing

# Run tests
pytest

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

# Run specific test file
pytest test_server.py

Code Quality

# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Lint code
flake8 src/ tests/

# Type checking
mypy src/

Development Setup

# 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)