ElevenLabs MCP Server

# 🖥️ Claude Desktop Integration Guide ## 🚀 Quick Start ### Option 1: Automatic Setup (Recommended) ```bash # Run the setup script python setup_claude_desktop.py # Enter your ElevenLabs API key when prompted # The script will automatically configure Claude Desktop ``` ### Option 2: Manual Setup ```bash # 1. Copy the configuration file cp claude_desktop_config_ready.json ~/Library/Application\ Support/Claude/claude_desktop_config.json # 2. Edit the file to add your API key nano ~/Library/Application\ Support/Claude/claude_desktop_config.json # 3. Replace "your-api-key-here" with your actual ElevenLabs API key ``` ## 📋 Step-by-Step Instructions ### Step 1: Get Your ElevenLabs API Key 1. Go to https://elevenlabs.io/app/settings/api-keys 2. Create a new API key if you don't have one 3. Copy the API key for use in the configuration ### Step 2: Configure Claude Desktop #### macOS Configuration Location: ```bash ~/Library/Application Support/Claude/claude_desktop_config.json ``` #### Windows Configuration Location: ```bash %APPDATA%/Claude/claude_desktop_config.json ``` #### Configuration Content: ```json { "mcpServers": { "elevenlabs": { "command": "python", "args": ["-m", "elevenlabs_mcp.server"], "cwd": "/Users/alex/claude/11-mcp", "env": { "ELEVENLABS_API_KEY": "your-actual-api-key-here", "PYTHONPATH": "/Users/alex/claude/11-mcp/src" } } } } ``` ### Step 3: Restart Claude Desktop 1. **Completely quit** Claude Desktop (Cmd+Q on macOS) 2. **Restart** Claude Desktop 3. **Wait** for the MCP server to initialize (may take 10-30 seconds) ### Step 4: Verify Connection Look for these indicators in Claude Desktop: - **MCP icon** in the interface - **Server connection status** showing "elevenlabs" as connected - **Tools available** indicator ## 🧪 Testing the Integration ### Test 1: Check MCP Server Status **Ask Claude:** "What MCP servers are connected?" **Expected Response:** ``` I can see that the ElevenLabs MCP server is connected with the following tools available: - Agent management tools (create_agent, list_agents, etc.) - Tool management tools (create_tool, list_tools, etc.) - Knowledge base tools (create_knowledge_base_from_text, etc.) ``` ### Test 2: List Available Tools **Ask Claude:** "What ElevenLabs tools are available?" **Expected Response:** ``` I have access to 18 ElevenLabs tools: Agent Management: - create_agent: Create new conversational AI agents - get_agent: Retrieve agent configuration - list_agents: List all agents with pagination - update_agent: Update existing agent settings - delete_agent: Remove agents Tool Management: - create_tool: Create webhook or client-side tools - get_tool: Retrieve tool configuration - list_tools: List all available tools - update_tool: Update tool settings - delete_tool: Remove tools Knowledge Base Management: - create_knowledge_base_from_text: Create KB from text - create_knowledge_base_from_url: Create KB from URL - get_knowledge_base_document: Retrieve document details - list_knowledge_base_documents: List all documents - update_knowledge_base_document: Update metadata - delete_knowledge_base_document: Remove documents - compute_rag_index: Generate RAG indices - get_document_content: Get full content and chunks ``` ### Test 3: List Your Agents **Ask Claude:** "List my ElevenLabs agents" **Expected Response:** ``` I'll list your ElevenLabs agents for you. [Claude will use the list_agents tool] Here are your ElevenLabs agents: [Shows your agents or indicates if you have none] ``` ### Test 4: Create a Simple Agent **Ask Claude:** "Create a simple customer service agent for my company" **Expected Response:** ``` I'll create a customer service agent for you. [Claude will use the create_agent tool with appropriate parameters] Agent created successfully! Here are the details: - Agent ID: agent_xxxxx - Name: Customer Service Agent - Language: English - Voice: [Selected voice] - Purpose: Customer support and assistance ``` ### Test 5: Knowledge Base Operations **Ask Claude:** "Show me my ElevenLabs knowledge base documents" **Expected Response:** ``` I'll check your ElevenLabs knowledge base documents. [Claude will use the list_knowledge_base_documents tool] Your knowledge base contains: [Lists your documents or indicates if empty] ``` ## 🔧 Troubleshooting ### Common Issues and Solutions #### Issue 1: MCP Server Not Connecting **Symptoms:** - No MCP icon in Claude Desktop - Server shows as disconnected - Tools not available **Solutions:** 1. Check configuration file syntax (must be valid JSON) 2. Verify file path is correct 3. Ensure Python can be found in PATH 4. Check working directory (`cwd`) exists 5. Restart Claude Desktop completely #### Issue 2: Import Errors **Symptoms:** - Server starts but immediately disconnects - Error messages about missing modules **Solutions:** 1. Verify `PYTHONPATH` is set correctly 2. Check that virtual environment is activated 3. Ensure all dependencies are installed 4. Try absolute paths instead of relative paths #### Issue 3: API Authentication Errors **Symptoms:** - Tools are available but return authentication errors - "Invalid API key" messages **Solutions:** 1. Verify your ElevenLabs API key is correct 2. Check API key permissions 3. Ensure no extra spaces in the API key 4. Try regenerating the API key #### Issue 4: Tool Execution Failures **Symptoms:** - Tools are listed but fail when executed - Network or timeout errors **Solutions:** 1. Check internet connectivity 2. Verify ElevenLabs API is accessible 3. Check firewall/proxy settings 4. Try with a different network ### Debug Configuration For detailed debugging, use this configuration: ```json { "mcpServers": { "elevenlabs": { "command": "python", "args": ["-m", "elevenlabs_mcp.server"], "cwd": "/Users/alex/claude/11-mcp", "env": { "ELEVENLABS_API_KEY": "your-actual-api-key-here", "PYTHONPATH": "/Users/alex/claude/11-mcp/src", "LOG_LEVEL": "DEBUG" } } } } ``` ### Viewing Logs #### Claude Desktop Logs: - **macOS**: `~/Library/Logs/Claude/` - **Windows**: `%APPDATA%/Claude/Logs/` #### MCP Server Logs: Set `LOG_LEVEL=DEBUG` in the environment variables to see detailed logs. ## 📊 Success Checklist After setup, verify these items: - [ ] Claude Desktop shows MCP server as connected - [ ] All 18 ElevenLabs tools are available - [ ] `list_agents` command works - [ ] `list_knowledge_base_documents` command works - [ ] Agent creation works - [ ] Error handling is appropriate - [ ] Performance is acceptable (responses within 5-10 seconds) ## 🎯 Example Workflows ### Workflow 1: Agent Management ``` You: "Create a customer service agent for my e-commerce store" Claude: [Creates agent with appropriate configuration] You: "List all my agents" Claude: [Shows all agents including the new one] You: "Update the customer service agent to be more friendly" Claude: [Updates the agent's prompt and configuration] ``` ### Workflow 2: Knowledge Base Management ``` You: "Create a knowledge base from this text: [paste company info]" Claude: [Creates knowledge base document] You: "Add this FAQ page to my knowledge base: https://example.com/faq" Claude: [Scrapes URL and creates knowledge base document] You: "Show me all my knowledge base documents" Claude: [Lists all documents with metadata] ``` ### Workflow 3: Tool Integration ``` You: "Create a webhook tool that gets customer data from my CRM" Claude: [Creates webhook tool with appropriate parameters] You: "Add this tool to my customer service agent" Claude: [Updates agent configuration to include the tool] ``` ## 🚨 Important Notes 1. **API Key Security**: Never commit your API key to version control 2. **Rate Limits**: Be aware of ElevenLabs API rate limits 3. **Costs**: Monitor your ElevenLabs usage for cost management 4. **Updates**: Keep the MCP server updated for new features ## 📞 Support If you encounter issues: 1. **Check the logs** first (Claude Desktop and MCP server) 2. **Verify configuration** with the test scripts 3. **Test network connectivity** to ElevenLabs API 4. **Review documentation** for troubleshooting steps --- **Ready to start?** Follow the Quick Start section above!