Elevenlabs Voice Agent MCP

ElevenLabs语音代理MCP服务器

用于开发和管理ElevenLabs语音代理的模型上下文协议（MCP）服务器。该服务器提供23个专用工具，用于通过Claude和其他MCP客户端创建、配置、测试、监控和部署语音代理。

特性

核心代理管理（第1层）

• elevenlabs_create_agent -创建具有完整配置的新语音代理
• 十一个_获取_代理 -检索代理详细信息和配置
• elevenlabs_update_agent -修改现有代理设置
• 十一人_删除_代理 -永久删除代理
• 十一位男士列表 -使用分页浏览所有代理

知识库和工具（第2层）

• elevenlabs_add_knowledge_base -向代理知识添加文档或URL
• elevenlabs_create_webhook_tool -为代理创建webhook集成
• elevenlabs_list_tools -查看为代理配置的所有工具
• elevenlabs_delete_tool -从代理中删除工具

测试和监控（第3级）

• 十一个字母_组_对话 -检索对话记录和分析
• 十一个列表_对话 -通过筛选浏览对话
• elevenlabs_generate_widget_code -生成用于测试的HTML嵌入代码

公用事业（第4级）

• elevenlabs_list_voices -通过过滤浏览可用语音

出站呼叫和电话管理（第5级）

• elevenlabs_start_outbound_call -通过Twilio发起单次出站呼叫
• elevenlabs_submit_batch_call -为多个收件人提交批处理呼叫作业
• elevenlabs_list_batch_calls -浏览所有批处理调用作业
• elevenlabs_get_batch_call -获取包含收件人信息的详细批处理呼叫状态
• 十一个电话号码列表 -列出所有已连接的电话号码
• 十一个电话号码 -获取电话号码详细信息和配置
• 十一个_进口_电话_号码 -导入Twilio电话号码
• elevenlabs_update_phone_number -更新电话号码设置（分配代理）
• 十一个_删除_电话_号码 -从工作区中删除电话号码

安装

先决条件

• Node.js 18或更高版本
• ElevenLabs API密钥(在这里买一个)

设置

1. 克隆或导航到项目目录：

   cd elevenlabs-voice-agent-mcp

1. 安装依赖项：

   npm install

1. 设置环境变量：

   cp .env.example .env
   # Edit .env and add your ElevenLabs API key

1. 构建项目：

   npm run build

配置

环境变量

创建 .env 项目根目录中的文件：

ELEVENLABS_API_KEY=your_elevenlabs_api_key_here

从获取API密钥 ElevenLabs设置.

Claude代码配置

使用Claude Code CLI直接安装MCP服务器：

claude mcp add --transport stdio elevenlabs-voice-agents \
  -e ELEVENLABS_API_KEY=your_key_here \
  -- npx -y elevenlabs-voice-agent-mcp

此命令：

• 添加名为的MCP服务器 elevenlabs-voice-agents
• 将ElevenLabs API密钥设置为环境变量
• 用途 npx 自动下载并运行最新版本

Claude桌面配置

将此添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "elevenlabs-voice-agents": {
      "command": "node",
      "args": [
        "/absolute/path/to/elevenlabs-voice-agent-mcp/dist/index.js"
      ],
      "env": {
        "ELEVENLABS_API_KEY": "your_elevenlabs_api_key_here"
      }
    }
  }
}

添加配置后：

1. 保存文件
2. 重新启动克劳德桌面
3. 寻找🔌 用于验证服务器是否已连接的图标

MCP客户端配置（通用客户端）

服务器使用 stdio传输。下面是流行客户端的现成配置。始终使用 绝对路径 用于本地构建和设置 ELEVENLABS_API_KEY 通过env（永远不要提交）。

快速查阅

常见片段

• 通过npx进行Stdio（自动更新）

{
  "mcpServers": {
    "elevenlabs-voice-agents": {
      "command": "npx",
      "args": ["-y", "elevenlabs-voice-agent-mcp"],
      "env": { "ELEVENLABS_API_KEY": "your_key_here" }
    }
  }
}

• Stdio通过本地建设（用于开发）

{
  "mcpServers": {
    "elevenlabs-voice-agents": {
      "command": "node",
      "args": ["/absolute/path/to/elevenlabs-voice-agent-mcp/dist/index.js"],
      "env": { "ELEVENLABS_API_KEY": "your_key_here" }
    }
  }
}

• 托管HTTP（如果你用mcp-remote等HTTP网桥包装stdio）\

仅当您使用HTTP传输来连接stdio服务器时使用：

{
  "mcpServers": {
    "elevenlabs-voice-agents": {
      "url": "https://your-hosted-mcp.example.com/mcp",
      "type": "http"
    }
  }
}

光标IDE

配置文件： ~/.cursor/mcp.json （macOS/Linux）或 %USERPROFILE%\.cursor\mcp.json （Windows）。

• 方法1（推荐，npx-stdio）： 使用 Stdio通过npx 上面的片段。
• 方法2（本地构建）： 使用 Stdio通过本地构建 片段。
• 保存后重新启动Cursor。通过扳手图标进行验证或运行MCP命令。
• 故障排除：确保绝对路径，检查 ELEVENLABS_API_KEY，并确认节点18+。

克劳德桌面版

配置文件： ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）。

• 方法1（npx-stdio）：

{
  "mcpServers": {
    "elevenlabs-voice-agents": {
      "command": "npx",
      "args": ["-y", "elevenlabs-voice-agent-mcp"],
      "env": { "ELEVENLABS_API_KEY": "your_key_here" }
    }
  }
}

• 方法2（本地构建）： 使用本地构建代码段并指向 dist/index.js.
• 重新启动克劳德桌面。在新的聊天中，问“你有什么工具？”进行验证。

克劳德代码CLI

运行（通过npx进行stdio）：

claude mcp add --transport stdio elevenlabs-voice-agents \
  -e ELEVENLABS_API_KEY=your_key_here \
  -- npx -y elevenlabs-voice-agent-mcp

对于本地构建，请替换 npx 部分与 node /absolute/path/to/dist/index.js.

Codex CLI

Codex CLI还支持stdio MCP服务器。配置类似：

codex mcp add --transport stdio elevenlabs-voice-agents \
  -e ELEVENLABS_API_KEY=your_key_here \
  -- npx -y elevenlabs-voice-agent-mcp

如果使用本地构建，请交换 npx -y elevenlabs-voice-agent-mcp 随着 node /absolute/path/to/dist/index.js.

VS代码（通过mcp.json）

添加 .vscode/mcp.json 到您的工作区：

{
  "servers": {
    "elevenlabs-voice-agents": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "elevenlabs-voice-agent-mcp"],
      "env": { "ELEVENLABS_API_KEY": "your_key_here" }
    }
  }
}

保存后重新启动VS Code。

远程托管（铁路示例）

MCP服务器首先是stdio。要托管它，请部署Node应用程序，如果需要HTTP，请用MCP HTTP桥将其包装，例如 mcp-remote.

1. 部署到铁路（节点18）：

• Repo:这个项目
• 环境变量： ELEVENLABS_API_KEY
• 启动命令： npm run build && npm start

1. 为HTTP MCP客户端公开（可选）：

• 添加正在运行的进程 npx -y mcp-remote http://0.0.0.0:3000 （或您选择的网桥）指向stdio服务器，或使用您控制的MCP HTTP包装器。相应地调整健康检查/端口。

1. 客户端配置（HTTP）：

• 使用 托管HTTP 包含您的铁路URL的代码片段。

其他托管服务（Render、Fly.io等）

• 基于部署构建： npm run build 然后 npm start.
• 集 ELEVENLABS_API_KEY 在平台的环境变量设置中。
• 如果平台仅支持HTTP。， mcp-remote)在stdio服务器前，使用托管的HTTP代码段。

故障排除（所有客户端）

• 服务器无法启动：请确保 ELEVENLABS_API_KEY 已设置；节点18+；跑 npm run build.
• 工具未出现：检查配置中的绝对路径，重新启动客户端，验证stdio传输。
• Auth错误：确认env中的API密钥；避免将密钥放在配置文件中。
• 路径问题：始终使用绝对路径 dist/index.js.
• 托管模式：确保您的HTTP网桥指向stdio服务器，并且URL是可访问的。

快速入门：外拨

1.导入Twilio电话号码

elevenlabs_import_phone_number({
  phone_number: "+14155551234",
  label: "Sales Line",
  sid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxx",  // Your Twilio Account SID
  token: "your_twilio_auth_token",
  provider: "twilio",
  supports_inbound: true,
  supports_outbound: true
})
// Returns: { phone_number_id: "pn_abc123" }

2.为代理人分配电话号码

elevenlabs_update_phone_number({
  phone_number_id: "pn_abc123",
  agent_id: "ag_xyz789"
})

3.拨打一个外呼

elevenlabs_start_outbound_call({
  agent_id: "ag_xyz789",
  agent_phone_number_id: "pn_abc123",
  to_number: "+19175551234",
  conversation_initiation_client_data: {
    dynamic_variables: {
      customer_name: "John Smith",
      account_balance: 1500
    }
  }
})

4.提交批量调用作业

elevenlabs_submit_batch_call({
  call_name: "Q4 Customer Survey",
  agent_id: "ag_xyz789",
  agent_phone_number_id: "pn_abc123",
  recipients: [
    {
      phone_number: "+14155551234",
      conversation_initiation_client_data: {
        dynamic_variables: {
          name: "Alice Johnson",
          account_id: "A123"
        }
      }
    },
    {
      phone_number: "+19175555678",
      conversation_initiation_client_data: {
        dynamic_variables: {
          name: "Bob Williams",
          account_id: "B456"
        }
      }
    }
  ]
})

5.监控批处理进度

elevenlabs_get_batch_call({
  batch_id: "batch_abc123"
})
// Shows status for each recipient: completed, in_progress, failed, voicemail, etc.

用法

创建语音代理

// Create a basic customer service agent
elevenlabs_create_agent({
  name: "Customer Support Bot",
  prompt: "You are a helpful customer service agent for TechCorp. Be friendly, professional, and solve customer issues efficiently.",
  llm: "gpt-4o-mini",
  voice_id: "21m00Tcm4TlvDq8ikWAM",
  first_message: "Hi! How can I help you today?",
  language: "en"
})

添加知识库

// Add company documentation
elevenlabs_add_knowledge_base({
  agent_id: "ag_abc123",
  documents: [
    {
      type: "url",
      content: "https://example.com/company-policies"
    },
    {
      type: "text",
      content: "Our support hours are Monday-Friday, 9 AM to 6 PM EST."
    }
  ]
})

创建Webhook工具

// Add order status checking capability
elevenlabs_create_webhook_tool({
  agent_id: "ag_abc123",
  name: "check_order_status",
  description: "Check the status of a customer order by order ID",
  url: "https://api.example.com/orders/status",
  method: "POST",
  parameters: [
    {
      name: "order_id",
      type: "string",
      description: "The unique order identifier",
      required: true
    }
  ]
})

测试您的代理

// Generate widget code for testing
elevenlabs_generate_widget_code({
  agent_id: "ag_abc123",
  color: "#4A90E2",
  avatar_url: "https://example.com/avatar.png"
})

监控对话

// List recent conversations
elevenlabs_list_conversations({
  agent_id: "ag_abc123",
  limit: 10,
  status: "completed"
})

// Get full transcript
elevenlabs_get_conversation({
  conversation_id: "conv_xyz789"
})

工具详细信息

响应格式

所有工具都支持两种响应格式：

• 标记语言 （默认）-人类可读的格式化输出
• JSON -用于编程的结构化数据

例子：

elevenlabs_get_agent({
  agent_id: "ag_abc123",
  response_format: "json"
})

分页

列表端点支持分页：

elevenlabs_list_agents({
  limit: 20,      // Items per page (1-100)
  offset: 0       // Skip this many items
})

答复包括：

• has_more -是否存在更多项目
• next_offset -下一页的偏移值
• total -项目总数

支持的LLM模型

MCP服务器接受任何有效的ElevenLabs型号标识符。常见选项包括：

• gpt-4o
• gpt-4o-mini （默认）
• claude-3-5-sonnet-20241022
• claude-3-5-haiku-20241022
• gemini-2.0-flash-exp

注： ElevenLabs可能会随着时间的推移添加新型号。您可以使用任何模型标识符，而无需更新MCP服务器代码——验证接受任何字符串值。

支持的语音模型

• eleven_turbo_v2_5 -最快、最低延迟
• eleven_flash_v2_5 （默认）-速度和质量平衡
• eleven_multilingual_v2 -最适合多种语言

支持的语言

en, es, fr, de, it, pt, pl, nl, ja, zh, ko, ar, hi

API 参考

按功能组织的所有23个MCP工具的完整参考。

第1层：核心代理管理

第2层：知识库和工具

第3层：测试和监控

第4层：公用事业

第5层：出站呼叫和电话管理

工具注释

所有工具都包括用于客户指导的MCP注释：

• readOnlyHint：工具是否只读取数据（无副作用）
• destructiveHint：工具是否执行破坏性操作（删除）
• idempotentHint：重复呼叫是否具有相同的效果
• openWorldHint：工具是否与外部系统交互

发展

项目结构

elevenlabs-voice-agent-mcp/
├── src/
│   ├── index.ts                 # Server initialization & tool registration
│   ├── types.ts                 # TypeScript interfaces for all entities
│   ├── constants.ts             # API URLs, limits, and defaults
│   ├── schemas/                 # Zod validation schemas
│   │   ├── agent-schemas.ts     # Agent CRUD schemas
│   │   ├── tool-schemas.ts      # Webhook tool & knowledge base schemas
│   │   ├── conversation-schemas.ts
│   │   ├── outbound-schemas.ts  # Single call schemas
│   │   ├── batch-calling-schemas.ts
│   │   ├── phone-number-schemas.ts
│   │   └── common-schemas.ts    # Shared schemas (pagination, etc.)
│   ├── services/                # API clients and utilities
│   │   ├── elevenlabs-api.ts    # HTTP client with auth
│   │   └── formatters.ts        # Response formatting (Markdown/JSON)
│   ├── tools/                   # MCP tool implementations
│   │   ├── agent-tools.ts       # CRUD for agents
│   │   ├── knowledge-tools.ts   # Knowledge base management
│   │   ├── tool-tools.ts        # Webhook tool management
│   │   ├── conversation-tools.ts
│   │   ├── utility-tools.ts     # Voices, widgets
│   │   ├── outbound-tools.ts    # Single outbound calls
│   │   ├── batch-calling-tools.ts
│   │   └── phone-number-tools.ts
│   └── utils/                   # Helper functions
│       ├── error-handlers.ts    # Error parsing & messages
│       ├── truncation.ts        # Response size management
│       └── phone-normalizer.ts  # E.164 format conversion
├── dist/                        # Compiled JavaScript (gitignored)
├── test/                        # Test files
└── CLAUDE.md                    # AI assistant guidance

脚本

环境变量

测试

该项目包括一个全面的测试套件 351个单元测试 实现 88%+代码覆盖率.

运行测试

# Run all unit tests
npm test

# Run tests in watch mode (re-runs on file changes)
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Run tests with UI (browser-based test runner)
npm run test:ui

# TypeScript type checking for test files
npm run test:types

# Run integration tests (requires API key)
npm run test:integration

测试结构

src/__tests__/
├── mocks/
│   └── fixtures.ts          # Mock data and test fixtures
├── schemas/
│   └── schemas.test.ts      # Zod schema validation tests
├── services/
│   ├── elevenlabs-api.test.ts  # API client tests
│   └── formatters.test.ts      # Response formatter tests
├── tools/
│   ├── agent-tools.test.ts        # Agent CRUD tests
│   ├── batch-calling-tools.test.ts
│   ├── conversation-tools.test.ts
│   ├── knowledge-tools.test.ts
│   ├── outbound-tools.test.ts
│   ├── phone-number-tools.test.ts
│   ├── tool-tools.test.ts
│   └── utility-tools.test.ts
├── utils/
│   ├── error-handlers.test.ts
│   └── truncation.test.ts
└── setup.ts                 # Test environment setup

覆盖阈值

测试套件强制执行最小覆盖阈值：

• 声明: 85%
• 分支: 75%
• 函数: 85%
• 线条: 85%

添加新工具

1. 创建架构 在 src/schemas/:

   export const MyToolSchema = z.object({
     param: z.string().describe("Parameter description"),
     response_format: ResponseFormatSchema
   }).passthrough();

1. 创建工具定义 在 src/tools/:

   export const elevenlabs_my_tool = {
     name: "elevenlabs_my_tool",
     description: `Tool description with examples...`,
     zodSchema: MyToolSchema,
     annotations: { readOnlyHint: true, ... },
     handler: async (args: unknown) => {
       const parsed = MyToolSchema.parse(args);
       // Implementation
       return { content: [{ type: "text", text: result }] };
     }
   };

1. 注册 src/index.ts:

   import { elevenlabs_my_tool } from "./tools/my-tools.js";
   // Add to tools array

1. 重建: npm run build

代码风格

• TypeScript严格模式已启用
• ESM模块 .js 扩大进口
• 用于运行时验证的Zod模式
• 通过一致的错误处理 handleElevenLabsError
• 响应格式支持Markdown和JSON

本地测试

1. 构建项目： npm run build
2. 设置API密钥： export ELEVENLABS_API_KEY=your_key
3. 使用MCP检查员或Claude Desktop进行测试
4. 检查stderr上的服务器输出以进行诊断

错误处理

服务器提供清晰、可操作的错误消息：

• 401未经授权 -API密钥无效，请检查 ELEVENLABS_API_KEY
• 404未找到 -代理/对话ID不存在
• 429价格有限 -请求太多，请等待60秒
• 400错误请求 -无效参数，请检查工具文档

字符限制

响应会自动截断为25000个字符，并有分页或过滤的指导。

最佳实践

代理创建

• 编写清晰、具体的系统提示
• 为您的用例测试不同的LLM模型
• 使用适当的语音模型（flash表示速度，多语言表示语言）
• 设置合理的温度值（0-0.7表示一致，0.8-2.0表示创意）

知识库

• 添加重点突出的相关文件
• 对经常更新的内容使用URL
• 包括元数据以更好地组织
• 保持文档简洁明了，结构良好

Webhook工具

• 提供清晰、描述性的工具名称
• 编写详细的参数说明
• 添加之前测试webhook端点
• 在webhook响应中优雅地处理错误

测试

• 生成小部件代码以便于浏览器测试
• 定期审查对话记录
• 监控对话分析指标
• 使用各种用户输入和边缘情况进行测试

故障排除

服务器无法启动

• 验证 ELEVENLABS_API_KEY 设置在环境中
• 检查Node.js版本（需要18+）
• 跑 npm install 确保安装了依赖项
• 如果运行多个MCP服务器，请检查端口冲突

工具未出现在Claude中

• 验证服务器是否已在中注册 claude_desktop_config.json
• 在配置中使用绝对路径
• 配置更改后重新启动Claude Desktop
• 检查Claude Desktop日志是否有错误

API错误

• 验证API密钥在 ElevenLabs设置
• 检查ElevenLabs帐户是否具有所需权限
• 确保您没有超过费率限制
• 验证代理/对话ID是否正确

支持

• ElevenLabs文档: https://elevenlabs.io/docs
• MCP文件: https://modelcontextprotocol.io
• 问题：通过GitHub问题报告错误或请求功能

许可证

麻省理工学院

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 通过测试进行更改
4. 提交拉取请求

用例

客户拓展

// Import leads from CSV and call them all
elevenlabs_submit_batch_call({
  call_name: "Lead Qualification Q1",
  agent_id: "ag_sales",
  recipients: [
    { phone_number: "+1...", conversation_initiation_client_data: { name: "...", company: "..." } },
    // ... up to 10,000 recipients
  ]
})

约会提醒

// Call customers with personalized reminders
elevenlabs_start_outbound_call({
  agent_id: "ag_scheduler",
  agent_phone_number_id: "pn_main",
  to_number: "+14155551234",
  conversation_initiation_client_data: {
    dynamic_variables: {
      patient_name: "Sarah",
      appointment_time: "3:00 PM tomorrow",
      doctor_name: "Dr. Smith"
    }
  }
})

调查和反馈收集

// Batch call for post-purchase surveys
elevenlabs_submit_batch_call({
  call_name: "Post-Purchase NPS Survey",
  agent_id: "ag_survey",
  recipients: recentCustomers.map(c => ({
    phone_number: c.phone,
    conversation_initiation_client_data: {
      dynamic_variables: {
        name: c.name,
        product: c.lastPurchase,
        order_id: c.orderId
      }
    }
  }))
})

更新日志

v2.0.0（2025-01-24）

• 新增9个用于外拨和电话管理的工具
• 通过Twilio集成进行出站呼叫
• 批量呼吁大规模外联（最多10000名收件人）
• 电话号码管理（导入、分配、配置）
• 支持动态变量和呼叫个性化
• 批处理呼叫中的语音邮件检测
• 工具总数：23（高于14）

v1.0.0（2025-01-20）

• 初始版本
• 14种语音代理开发工具
• 全面的代理商管理
• 知识库和webhook工具支持
• 对话监控和分析
• 用于测试的小部件生成