MCP Telephone

MCP电话-AI电话呼叫服务

模型上下文协议（MCP）服务器，使LLM能够使用OpenAI的实时API和Twilio进行电话呼叫。该项目将OpenAI Realtime+Twilio演示转换为生产就绪的MCP电话服务，可供任何兼容MCP的客户端使用，如Claude Desktop或Cursor IDE。

什么是MCP？

模型上下文协议（MCP）是一个开放标准，可实现LLM和外部数据源或工具之间的无缝集成。该项目实现了一个公开电话功能的MCP服务器，允许任何兼容MCP的LLM以编程方式拨打和管理电话。

特性

• 🤖 MCP电话工具：四种强大的电话操作工具

- telephony.call -使用人工智能代理拨打外拨电话 - telephony.status -实时查看通话进度 - telephony.cancel -终止正在进行的通话 - telephony.transcript -检索通话记录

• 🔌 多个传输：MCP通信的HTTP和WebSocket支持
• 📞 Twilio集成：通过Twilio拨打生产就绪电话
• 🎙️ OpenAI实时API：与人工智能进行自然语音对话
• 📝 呼叫管理：跟踪通话状态、目标和结果
• 🔒 安全：存储在环境变量中的所有凭据

快速设置

打开三个终端窗口：

确保所有变量都已输入 webapp/.env 和 websocket-server/.env 设置正确。看 完整设置 部分了解更多。

概述

这个repo使用Realtimeneneneba API和Twilio实现了一个电话呼叫助手，并且有两个主要部分： webapp，以及 websocket-server.

1. webapp：NextJS应用程序作为呼叫配置和转录的前端
2. websocket-server：Express后端处理来自Twilio的连接，将其连接到Realtime API，并将消息转发到前端

Twilio使用TwiML（一种XML形式）来指定如何处理电话。当呼叫到来时，我们告诉Twilio启动到后端的双向流，我们在呼叫和Realtime API之间转发消息。 ({{WS_URL}} 被替换为我们的websocket端点。)

  Connected
  
    
  
  Disconnected

我们使用 ngrok 使Twilio能够访问我们的服务器。

电话的生活

设置

1. 我们运行ngrok是为了让Twilio可以访问我们的服务器
2. 我们将Twilio webhook设置为我们的ngrok地址
3. 前端连接到后端(wss://[your_backend]/logs)，准备接听电话

呼叫

1. 拨打Twilio管理的号码
2. Twilio查询webhook(http://[your_backend]/twiml)TwiML指令
3. Twilio打开到后端的双向流(wss://[your_backend]/call)
4. 后端连接到实时API，并开始转发消息：

- Twilio和实时API之间 - 在前端和实时API之间

函数调用

此演示模拟了函数调用，因此您可以提供示例响应。实际上，您可以处理函数调用，执行一些代码，然后将响应提供回模型。

完整设置

1. 确保你的 auth和env 配置正确。

1. 运行webapp。

cd webapp
npm install
npm run dev

1. 运行websocket服务器。

cd websocket-server
npm install
npm run dev

详细授权与环境

OpenAI和Twilio

在中设置您的凭据 webapp/.env 和 websocket-server -看 webapp/.env.example 和 websocket-server.env.example 以供参考。

恩格洛克

Twilio需要能够访问您的websocket服务器。如果你在本地运行它，默认情况下你的端口是不可访问的。 ngrok 可以使它们暂时可用。

我们已经设定了 websocket-server 在港口运行 8081 默认情况下，这就是我们要转发的端口。

ngrok http 8081

记下 Forwarding URL。（例如。 https://54c5-35-170-32-42.ngrok-free.app)

Websocket URL

您的服务器现在应该可以在以下位置访问 Forwarding 运行时使用URL，因此设置 PUBLIC_URL 在……里面 websocket-server/.env。参见 websocket-server/.env.example 以供参考。

在Cursor IDE中使用MCP

1.配置光标

将MCP服务器添加到Cursor配置文件中 .cursor/mcp.json:

{
  "mcpServers": {
    "mcp-telephone": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8081/mcp"
      }
    }
  }
}

对于WebSocket传输：

{
  "mcpServers": {
    "mcp-telephone": {
      "transport": {
        "type": "websocket",
        "url": "ws://localhost:8081/mcp/ws"
      }
    }
  }
}

2.在光标中使用MCP工具

配置后，您可以要求Cursor拨打电话：

"Use the telephony.call tool to call +1234567890 and book a table for 2 at 7:30pm tonight at Restaurant Name. Be polite and professional."

人工智能将使用MCP工具：

1. 拨打电话
2. 进行一次自然的对话
3. 完成请求的任务
4. 返回结果

MCP工具文档

电话

拨打人工智能代理的出站电话。

参数：

• to （字符串，必填）：要拨打的电话号码（E.164格式，例如“+1234567890”）
• from （字符串，必填）：您的Twilio电话号码（E.164格式）
• goal （string，必填）：人工智能在通话中应该完成什么
• context （object，可选）：AI的附加上下文
• instructions （字符串，可选）：特定行为指令
• timeoutSec （数字，可选）：最大通话持续时间（秒）（默认值：180）

退货：

• callId：用于跟踪呼叫的唯一标识符

例子：

{
  "to": "+14155551234",
  "from": "+13156303570",
  "goal": "Book a dinner reservation for 2 people",
  "context": {
    "restaurant": "Via Carota",
    "date": "Friday",
    "time": "7:30pm",
    "party_size": 2
  },
  "instructions": "Be polite and professional. If they ask for a name, say 'Smith'.",
  "timeoutSec": 120
}

电话状态

检查通话的当前状态。

参数：

• callId （string，必填）：telehony.call返回的ID

退货：

• state：当前呼叫状态（“拨号”、“已连接”、“完成”、“失败”、“取消”）
• duration：呼叫持续时间（秒）
• result：呼叫结果（如果已完成）
• error：错误消息（如果失败）

电话取消

取消正在进行的通话。

参数：

• callId （string，必填）：要取消的呼叫的ID

退货：

• success：布尔值，表示取消是否成功
• message：状态消息

电话记录

检索通话的完整记录。

参数：

• callId （string，必填）：呼叫的ID

退货：

• transcript：带有时间戳的对话回合数组
• state：当前通话状态
• duration：总通话时长
• result：通话结果

测试MCP端点

列出可用工具

curl -X POST http://localhost:8081/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

拨打测试电话

curl -X POST http://localhost:8081/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"telephony.call",
      "arguments":{
        "to":"+1234567890",
        "from":"+10987654321",
        "goal":"Test the phone system",
        "context":{"test":true}
      }
    }
  }'

建筑

MCP电话服务由三个主要部分组成：

1. MCP服务器 (websocket-server/src/mcp/)

- 处理JSON-RPC 2.0请求 - 提供HTTP和WebSocket传输 - 将工具调用路由到适当的服务

1. 呼叫管理 (websocket-server/src/svc/)

- 管理呼叫状态和生命周期 - 与Twilio API集成 - 跟踪成绩单和结果

1. 会话桥 (websocket-server/src/sessionManager.ts)

- 连接Twilio↔ OpenAI实时API - 将通话目标注入AI提示中 - 捕获实时成绩单

重要提示

Twilio试用帐户限制

如果使用Twilio试用帐户：

• 拨打未经验证的号码将首先播放试用消息
• 收件人必须按键才能继续
• 对于生产用途，升级到付费的Twilio帐户

安全考虑

• 永不承诺 .env 文件或公开API密钥
• 对所有凭据使用环境变量
• 为生产部署实施身份验证
• 考虑对公共端点进行速率限制

生产部署

用于生产用途：

1. 将Twilio帐户从试用版升级为付费版
2. 在MCP端点上实施正确的身份验证
3. 使用持久存储而不是内存存储
4. 添加监控和日志记录
5. 实施速率限制
6. 对所有连接使用HTTPS/WSS

贡献

欢迎投稿！请确保：

• 没有硬编码凭据
• 新功能测试
• 文档更新
• 遵循现有代码样式

许可证

麻省理工学院

致谢

构建在OpenAI实时API+Twilio演示之上。增强了对LLM集成的模型上下文协议支持。