Voice Assistant MCP Server

语音助手 MCP 服务

强大的 Model Context Protocol (MCP) 服务，集成了 Twilio Voice、Deepgram AI 和 OpenAI，用于创建智能语音 HR 自动化工具。该系统支持 Claude 等 AI 助手通过自然语音对话进行电话面试、发送通知和管理 HR 沟通。

演示视频

https://github.com/user-attachments/assets/6c47a8b7-7428-4711-bf26-00d5951ec66f

功能

核心能力

• AI 驱动的语音面试：使用 AI 与候选人进行专业电话面试
• 面试结果通知：自动致电候选人，告知面试结果并提供反馈
• 职位机会邀约：联系潜在候选人，介绍新的职位
• 实时语音处理：由 Deepgram 的 Voice Agent API 提供支持
• MCP 集成：与 Claude 及其他兼容 MCP 的 AI 助手无缝集成

技术特性

• 基于 WebSocket 的媒体流：通过 Twilio Media Streams 实时处理音频
• 动态提示词注入：根据通话目的提供上下文相关的 AI 提示词
• 函数调用处理：通过高级 AI 函数调用管理通话
• 全面的日志记录：提供详细日志，用于调试和监控
• 环境配置：安全管理凭据

架构

sequenceDiagram
    participant Claude as MCP Client(Claude App)
    participant MCP as MCP Server
    participant Twilio as Twilio Voice
    participant Deepgram as Deepgram
    participant AI as OpenAI

    %% Step 1: Initiate interaction
    Claude->>MCP: Initiate voice action (e.g., interview, notification)
    MCP->>Twilio: Setup voice call
    Twilio-->>MCP: Call status updates

    %% Step 2: Real-time audio processing
    Twilio->>Deepgram: Start audio stream
    Deepgram-->>AI: Transcribed text
    AI->>Deepgram: LLM response
    Deepgram->>Twilio: Stream audio

先决条件

设置项目之前，请确保具备以下条件：

1. Node.js（v22 或更高版本）
2. Twilio 账号，包括：
   • Account SID
   • Auth Token
   • Phone Number（用于拨出电话）
3. Deepgram 账号及 API Key
4. 用于 Webhook 的公开 URL（ngrok 或生产服务器）

安装

1. 克隆代码仓库：

   git clone https://github.com/prakharbhardwaj/voice-agent-mcp-server.git
   cd voice-agent-mcp-server
   

2. 安装依赖项：

   npm install
   

3. 环境配置： 在根目录中创建 .env 文件：

   # Server Configuration
   PORT=3000
   SERVER_URL=your_ngrok_url_or_server_url
   
   # Twilio Credentials
   TWILIO_ACCOUNT_SID=your_twilio_account_sid
   TWILIO_AUTH_TOKEN=your_twilio_auth_token
   TWILIO_PHONE_NUMBER=+your_twilio_phone_number
   
   # Deepgram API Key
   DEEPGRAM_API_KEY=your_deepgram_api_key
   

4. 配置 MCP 服务： 使用实际路径和凭据更新 mcp-config.json：

   {
     "mcpServers": {
       "voice-agent-mcp-server": {
         "type": "stdio",
         "command": "node",
         "args": ["/path/to/your/voice-agent-mcp-server/mcp-server.js"],
         "env": {
           "NODE_ENV": "production",
           "SERVER_URL": "your_ngrok_url_or_server_url",
           "TWILIO_ACCOUNT_SID": "your_twilio_account_sid",
           "TWILIO_AUTH_TOKEN": "your_twilio_auth_token",
           "TWILIO_PHONE_NUMBER": "+your_twilio_phone_number"
         }
       }
     }
   }
   

使用方法

启动 Web 服务器

npm run dev

在 Claude Desktop 中使用

1. 将 MCP 服务配置添加到 Claude Desktop 的设置中：
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
2. 重启 Claude Desktop
3. 在与 Claude 的对话中使用可用工具

可用的 MCP 工具

1. conduct_interview

发起语音通话，与候选人进行专业面试。

参数：

• candidatePhone（string）：采用 E.164 格式的电话号码
• candidateName（string）：候选人的姓名
• position（string）：候选人申请的职位
• interviewQuestions（array）：要提问的问题列表

示例：

Conduct an interview with John Doe at +1234567890 for the Software Engineer position.
Ask about their experience with React, their problem-solving approach, and their career goals.

2. notify_interview_result

致电候选人，告知其面试结果。

参数：

• candidatePhone（string）：采用 E.164 格式的电话号码
• candidateName（string）：候选人的姓名
• position（string）：候选人参加面试的职位
• result（enum）："accepted"、"rejected" 或 "next_round"
• message（string）：补充反馈信息

示例：

Call Jane Smith at +1234567890 to let her know she's been accepted for the Product Manager role.

3. discuss_job_opening

联系潜在候选人，介绍职位机会。

参数：

• candidatePhone（string）：采用 E.164 格式的电话号码
• candidateName（string）：潜在候选人的姓名
• position（string）：要讨论的职位
• companyInfo（string）：公司和职位的简要信息
• nextSteps（string）：如果候选人感兴趣，后续要采取的步骤

4. get_call_status

获取正在进行的语音通话状态和系统运行状况。

5. check_twilio_config

验证 Twilio 配置和服务就绪状态。

项目结构

├── index.js                   # Main Fastify server
├── mcp-server.js              # MCP server implementation
├── mcp-config.json            # MCP configuration
├── package.json               # Dependencies and scripts
└── src/
    ├── SettingsConfiguration.js   # Deepgram agent settings
    ├── config/
    │   └── dotenv.js              # Environment configuration
    ├── mcp/
    │   ├── logger.js              # Logging utilities
    │   ├── prompts.js             # AI prompt generators
    │   ├── server.js              # MCP server logic
    │   └── tools.js               # MCP tool definitions
    ├── routes/
    │   └── twilioRoute.js         # Twilio webhook handlers
    ├── services/
    │   ├── functionCallHandler.js # AI function call processing
    │   └── twilioService.js       # Twilio API wrapper
    └── websockets/
        └── mediaStreamHandler.js  # WebSocket media processing

配置详情

Deepgram Agent 设置

系统使用 Deepgram 的 Voice Agent，并采用以下配置：

• 语音识别：Nova-3 模型
• 文本转语音：Aura-2 Asteria 语音
• LLM 集成：OpenAI GPT-4o-mini
• 音频格式：8kHz μ-law 编码（兼容 Twilio）

Twilio 集成

• 媒体流：通过 WebSocket 实时传输音频
• TwiML：使用自定义参数进行动态呼叫路由
• 呼叫管理：状态跟踪和呼叫控制

故障排除

常见问题

1. Twilio webhook 未收到呼叫：

   • 确保 SERVER_URL 可通过公网访问
   • 检查 ngrok 是否正在运行，以及 URL 是否已更新
   • 验证 TwiML 配置

2. Deepgram 连接问题：

   • 验证 DEEPGRAM_API_KEY
   • 检查 WebSocket 连通性
   • 检查音频格式兼容性

3. MCP 服务未在 Claude 中加载：

   • 验证 mcp-config.json 中的路径是否为绝对路径
   • 检查是否已设置所有环境变量
   • 更改配置后重启 Claude Desktop

调试

查看控制台输出和 src/mcp/mcp-server.log 文件，以启用详细日志记录。

开发

在开发模式下运行

# Start web server with auto-reload
npm run dev

添加新工具

1. 在 src/mcp/tools.js 中定义工具
2. 在 src/mcp/prompts.js 中添加提示词生成逻辑
3. 在 src/mcp/server.js 中实现工具处理程序

安全注意事项

• 将所有凭据存储在环境变量中
• 在生产环境中使用 HTTPS/WSS
• 验证电话号码和输入数据
• 在生产环境中实施速率限制
• 遵循 Twilio 安全最佳实践

贡献

1. Fork 此代码库
2. 创建功能分支
3. 进行更改
4. 视情况添加测试
5. 提交拉取请求

已知问题

与 Claude Desktop 的 ES 模块兼容性

如果使用此 MCP 服务连接 Claude Desktop 时遇到 SyntaxError: Unexpected identifier，这是因为 Claude Desktop 无法访问与终端相同的 PATH 环境或工作目录上下文。

根本原因：Claude Desktop 可能无法找到你在终端中使用的同一个 Node.js 二进制文件（尤其是在使用 nvm 时），也可能无法从能够找到包含 "type": "module" 的 package.json 的项目目录启动。

解决方案：在 Claude Desktop 配置中使用 Node.js 二进制文件的绝对路径：

{
  "mcpServers": {
    "voice-agent-mcp-server": {
      "type": "stdio",
      "command": "/Users/yourusername/.nvm/versions/node/v22.16.0/bin/node",
      "args": ["/path/to/your/project/mcp-server.js"],
      "env": {
        // ... your environment variables
      }
    }
  }
}

要点：

• 使用 Node.js 二进制文件的绝对路径（运行 which node 查找）
• 将 cwd 设置为项目目录，以便 Node.js 能够找到 package.json
• 这样可确保 Claude Desktop 使用正确的 Node.js 和项目上下文

相关问题：MCP Servers Issue #64

支持

如有问题或疑问：

1. 查看故障排除部分
2. 查看 src/mcp/mcp-server.log 中的日志
3. 在代码库中提出问题

---

使用 Twilio、Deepgram 和 Model Context Protocol 构建