Agentphone

AgentPhone MCP Server

通过 Model Context Protocol 为 AI Agent 提供真实电话号码、短信和语音通话功能。

AgentPhone 让你的 AI Agent 通过 Cursor、Claude Desktop 或任何兼容 MCP 的客户端，使用自然语言购买电话号码、发送和接收短信，以及拨打语音电话。

Agent 是核心概念——每个 Agent 都有自己的电话号码、语音个性、系统提示词和 webhook。可以把 Agent 想象成拥有专属电话线路的虚拟团队成员。你可以为不同用途（客服、销售、日程安排）创建 Agent，并配置它们在通话中的声音和行为。

快速开始

1. 获取 API 密钥

在 agentphone.ai 注册，然后从 Settings 创建 API 密钥。

2. 通过 MCP 连接

选项 A：远程服务（推荐）

将 MCP 客户端指向托管端点——无需安装：

{
  "mcpServers": {
    "agentphone": {
      "type": "streamable-http",
      "url": "https://mcp.agentphone.ai/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key_here"
      }
    }
  }
}

适用于任何支持 Streamable HTTP 传输的 MCP 客户端（Switchboard、远程 Agent 平台等）。

选项 B：本地服务（stdio）

通过 npx 在本地运行——适用于 Cursor、Claude Desktop、Windsurf 和 Claude Code：

Cursor： Settings > MCP 或 ~/.cursor/mcp.json Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）

{
  "mcpServers": {
    "agentphone": {
      "command": "npx",
      "args": ["-y", "agentphone-mcp"],
      "env": {
        "AGENTPHONE_API_KEY": "your_api_key_here"
      }
    }
  }
}

选项 C：自托管 HTTP 服务

运行你自己的 HTTP MCP 端点：

PORT=3000 npx agentphone-mcp --http

然后连接到 http://localhost:3000/mcp，并将 MCP 客户端配置为在每个请求中发送 Authorization: Bearer <your AgentPhone API key>。仅设置服务端的 AGENTPHONE_API_KEY 并不能授权 HTTP 调用方。

警告： AGENTPHONE_ALLOW_ANONYMOUS=true 表示选择使用服务端的 AGENTPHONE_API_KEY 来处理没有 Authorization 标头的请求，但仅在 OAuth 关闭时生效。任何能够访问该端点的人都可以操作此账户：只有在你自己的身份验证机制后方可启用此选项。格式错误的标头会被拒绝，调用方提供的 bearer 永远不会被服务端密钥替代。

它能做什么？

配置完成后，只需向 AI Agent提出以下请求：

• “给我买一个 415 区号的电话号码”
• “创建一个客服 Agent，向来电者问候并协助处理账单问题”
• “拨打 +14155551234，聊聊预约牙医的时间安排”
• “给 +14155551234 发短信，说‘你的预约已确认，时间是明天下午 3 点’”
• “显示我最近的通话和转录文本”
• “列出可用的语音，并将我的 Agent 切换为另一种语音”
• “设置 webhook，让我在有人拨打或给我的号码发短信时收到通知”
• “显示本月的用量明细”

传输与托管

该服务基于 mcp-use 服务框架构建，由该框架负责 HTTP 层：Streamable HTTP、SSE 流、会话管理和 OAuth 发现端点。npm start（或 Docker 镜像）会在 PORT（默认值为 3000）上将其作为 HTTP 服务运行，可通过 /mcp 访问。

• 托管： https://mcp.agentphone.ai/mcp
• 自托管： PORT=3000 npm start → http://localhost:3000/mcp

身份验证

1. OAuth（推荐终端用户使用）：框架会将 Authorization Code + PKCE 流程代理到 AgentPhone 授权服务器，因此客户端会打开浏览器，在 agentphone.ai 登录——无需粘贴密钥。设置 MCP_OAUTH_CLIENT_ID（在 AgentPhone AS 预注册的客户端）即可启用。MCP_OAUTH_CLIENT_SECRET 为可选项：设置后可将网关作为机密客户端运行；留空则作为公共客户端运行（此时网关必须使用 token_endpoint_auth_method=none 注册）。公共模式会向下游客户端声明 none，严格的 OAuth 客户端要求如此。
2. **API 密钥（脚本／单租户，关闭 OAuth）：**每个请求都会发送 Authorization: Bearer <your API key>。服务端的 AGENTPHONE_API_KEY 仅用于未发送任何内容的调用方，且仅在 AGENTPHONE_ALLOW_ANONYMOUS=true 时使用。未设置该标志时，未通过身份验证的调用会被拒绝，因此暴露的端口无法被用来访问你的账户。

启用 OAuth 后，承载令牌会通过后端的 /auth/me 进行验证；选择启用匿名访问不会绕过此验证。

调用方的凭据会转发到 AgentPhone REST API 进行验证。可选的匿名模式则改用已配置的服务端 API 密钥。

环境变量

变量	用途
PORT	HTTP 端口（默认值为 3000）
AGENTPHONE_API_KEY	OAuth 关闭时使用的备用 API 密钥。仅当 AGENTPHONE_ALLOW_ANONYMOUS=true 且调用方未发送 Authorization 标头时使用
AGENTPHONE_ALLOW_ANONYMOUS	默认关闭；启用 OAuth 时会忽略。设为 true 后，不带 Authorization 标头的请求将使用服务端的 AGENTPHONE_API_KEY 进行操作。任何能够访问该端口的人都可以控制此账户：请先将服务部署在你自己的身份验证机制之后
MCP_OAUTH_CLIENT_ID	启用 OAuth；这是在 AgentPhone AS 预注册的网关客户端
MCP_OAUTH_CLIENT_SECRET	可选。设置 = 机密网关；留空 = 公共客户端（网关使用 token_endpoint_auth_method=none 注册，并向下游声明 none）
AGENTPHONE_BASE_URL	API 基础 URL（默认值为 https://api.agentphone.ai）
AGENTPHONE_OAUTH_AUTHORIZE	覆盖授权／同意 URL（默认值为 https://agentphone.ai/oauth/authorize）
AGENTPHONE_MCP_PUBLIC_URL	访问此服务的公开基础 URL，会发布在 /.well-known/mcp.json 安装清单中（例如 https://mcp.agentphone.ai）。若未设置，则根据请求推导。

亮点

• 电话号码 — 购买和管理任意美国／加拿大区号的号码
• 短信 — 发送和接收短信，查看对话线程
• 语音通话 — 使用内置 AI 对话功能拨打电话（无需 webhook），或接入你自己的 webhook
• 来电处理 — 设置 webhook，实时接收并回复来电和短信
• Agent — 创建具有自定义语音、系统提示词、呼叫转接和语音信箱的 Agent
• 用量与计费 — 监控号码用量、消息／通话／webhook 数量，以及每日／每月明细

所有工具（28）

账户

工具	说明
account_overview	获取账户完整概况 — 包括 Agent、号码、webhook 和用量
get_usage	获取用量统计 — 包括号码用量、计费短信段数，以及消息／通话／webhook 数量。使用 breakdown 查看每日或每月时间序列数据。

电话号码

工具	说明
list_numbers	列出账户中的所有电话号码
buy_number	购买新电话号码，可选指定 area_code 和 agent_id

短信

工具	描述
send_message	发送短信或 iMessage。支持媒体、线程回复（reply_to_message_id）、iMessage 发送效果（send_style）和群聊
get_messages	获取指定号码的消息
list_conversations	列出短信对话。传入 agent_id 可按 Agent 筛选。
get_conversation	获取包含完整消息历史记录的对话
update_conversation	设置对话的元数据

联系人

工具	描述
list_contacts	列出已保存的联系人（通讯录）。使用 search 词条筛选。
manage_contact	创建、更新或删除联系人（设置 action）

语音通话

工具	描述
list_calls	列出通话。可按 agent_id、number_id、状态、方向或关键词筛选。
get_call	获取通话详情和转录文本
make_call	发起外呼（由 webhook 驱动）
make_conversation_call	发起内置 AI 对话的通话——无需 webhook

Agents

工具	描述
list_agents	列出所有 Agent 及其号码和语音配置
create_agent	创建 Agent，并设置语音、系统提示词、通话转接、语音信箱和语音调节（语速、打断敏感度、附和语、语言等）
update_agent	更新 Agent 的配置
delete_agent	删除 Agent（号码会保留，但取消分配）
get_agent	获取 Agent 详情，包括电话号码和语音配置
attach_number	将电话号码分配给 Agent
detach_number	从 Agent 移除电话号码
list_voices	列出 Agent 可用的语音

Webhook

所有 webhook 工具都接受可选的 agent_id——传入该参数可管理特定 Agent 的 webhook，省略则使用项目级默认设置。Agent webhook 的优先级高于项目级设置。

工具	描述
get_webhook	获取 webhook 配置
set_webhook	为入站消息和通话事件设置 webhook URL
delete_webhook	移除 webhook
test_webhook	发送测试事件，以验证 webhook 是否正常工作
list_webhook_deliveries	查看投递历史记录以进行调试

get_webhook 和 set_webhook 默认会对两个作用域的签名密钥进行遮蔽。 如有可能，请从控制面板获取密钥。传入 reveal_secret: true 会在工具输出中包含密钥，使其暴露给模型上下文、转录文本和客户端日志。 这可防止意外泄露；但对于刻意请求密钥的模型而言，这并不构成授权边界。

环境变量

变量	必需	描述
AGENTPHONE_API_KEY	stdio：是；HTTP 匿名模式：是	在 HTTP 模式下，仅当设置了 AGENTPHONE_ALLOW_ANONYMOUS=true、关闭 OAuth 且调用方没有 Authorization 标头时使用
AGENTPHONE_ALLOW_ANONYMOUS	否	显式启用 HTTP 服务密钥回退；默认为关闭，启用 OAuth 时会忽略。请参阅上文的自托管警告
AGENTPHONE_BASE_URL	否	覆盖 API 基础 URL（默认为 https://api.agentphone.ai）
PORT	否	HTTP 模式的端口（默认为 3000；使用 PORT 设置）

开发

git clone https://github.com/AgentPhone-AI/agentphone-mcp.git
cd agentphone-mcp
npm install
npm run dev     # Run with tsx (hot reload)
npm run build   # Compile TypeScript
npm start       # Run compiled JS (stdio)

工作原理

此 MCP 服务将你的 AI 助手连接到 AgentPhone API。你的助手与 MCP 服务通信，MCP 服务调用 AgentPhone API，而 AgentPhone API 再与电话网络通信。

Your AI Assistant  <-->  agentphone-mcp  <-->  AgentPhone API  <-->  Phone Network

外呼：你的助手通过 AgentPhone API 发起通话和发送短信。

入站：当有人拨打你的号码或向其发送短信时，AgentPhone 会向你的服务发送 webhook 事件——随后你可以通过编程方式回复，或让 Agent 内置的 AI 处理。

许可证

MIT