内容
# voxplo-mcp
给你的 AI 代理一个电话号码。这个 MCP 服务器允许任何 MCP 客户端（Claude、Cursor、ChatGPT 开发模式等）通过 [Voxplo](https://voxplo.ai) 进行真正的 outbound AI 电话呼叫：AI 调用一个人，进行对话以实现目标，并返回摘要、记录和结构化的提取字段。
- **托管（远程）服务器：** `https://mcp.voxplo.ai/mcp`（可流式 HTTP + OAuth，无需安装）
- **本地（stdio）服务器：** `npx voxplo-mcp`（此软件包）
- **文档：** https://voxplo.ai/docs/agent-api/mcp
- **工具：** `place_call`、`set_appointment`、`get_call`、`list_calls`
## 选项 A：托管服务器（推荐）
无需安装。将 `https://mcp.voxplo.ai/mcp` 添加为客户端的远程 MCP 服务器：
```json
{
"mcpServers": {
"voxplo": { "type": "streamable-http", "url": "https://mcp.voxplo.ai/mcp" }
}
}
```
在 Claude 中：设置，然后连接器，然后“添加自定义连接器”，粘贴 `https://mcp.voxplo.ai/mcp`。您的浏览器会打开 Voxplo 的同意屏幕；通过从 [开发者页面](https://voxplo.ai/account/developers) 粘贴 Agent API 密钥来批准。客户端永远不会看到密钥本身，只会看到 OAuth 令牌。
## 选项 B：本地服务器（此软件包）
先决条件：Node 18+，Voxplo Agent API 密钥（以 `bys_ak_` 开头，从您的 [开发者页面](https://voxplo.ai/account/developers)）。
### Claude 桌面版
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或您所在操作系统的等效位置：
```json
{
"mcpServers": {
"voxplo": {
"command": "npx",
"args": ["-y", "voxplo-mcp"],
"env": { "VOXPLO_API_KEY": "bys_ak_your_key_here" }
}
}
}
```
### Cursor
将相同的块添加到项目中的 `.cursor/mcp.json`（或全局 `~/.cursor/mcp.json`）。
要指向预发布或自托管实例，请在 `env` 块中添加 `"VOXPLO_API_BASE": "https://staging.example.com"`。
## 工具
### `place_call`
拨打 outbound AI 电话以实现目标。立即返回 `callId`；调用异步运行。使用 `callId` 轮询 `get_call` 直到状态为终端。
**输入：**
| 字段 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `to` | 字符串 | 是 | E.164 中的目标号码（例如 `+14155550123`） |
| `objective` | 字符串 | 是 | 调用应实现的目标 |
| `context` | 字符串 | 否 | 助手后台上下文 |
| `fields` | 数组 | 否 | 要提取的结构化字段（最多 20 个项目：`{ name, type?, description? }`） |
| `webhookUrl` | 字符串 | 否 | 调用结束时接收签名结果的 HTTPS URL |
| `callerId` | 字符串 | 否 | Caller ID 覆盖；必须是您账户中的号码 |
**返回：** `{ callId, status }` 其中 `status` 在成功时为 `queued`。
### `set_appointment`
拨打 outbound AI 电话以设置会议。助手调用人员，同意时间，结果（轮询 `get_call`）带有 `outcome`（`appointment_set | callback_requested | declined | no_answer | failed`）和（设置时）会议详情（`startISO`, `timezone`, `durationMinutes`, `attendee`, `subject`）。立即返回 `callId`。
**输入：**
| 字段 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `to` | 字符串 | 是 | E.164 中的呼叫对象 |
| `subject` | 字符串 | 是 | 会议主题 |
| `durationMinutes` | 数字 | 否 | 会议时长（分钟，默认为 30） |
| `timePreference` | 字符串 | 否 | 自然语言窗口，例如“下周工作日上午” |
| `slots` | 数组 | 否 | 特定开始时间提供：`[{ startISO }]`, ISO-8601 含偏移量 |
| `timezone` | 字符串 | 否 | 会议的 IANA 时区，例如 `Asia/Jerusalem` |
| `autoBook` | 布尔值 | 否 | 还要在连接的日历上预订同意的时间 |
| `webhookUrl` | 字符串 | 否 | 接收签名结果的 HTTPS URL |
| `callerId` | 字符串 | 否 | Caller ID 覆盖；必须是您账户中的号码 |
### `get_call`
获取调用的当前状态和结果。
**输入：**
| 字段 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `callId` | 字符串 | 是 | `place_call` 或 `set_appointment` 中的 `callId` |
**返回：** `{ id, status, summary, transcript, extracted, recordingUrl, to, objective, startedAt, endedAt, durationSec, error? }`
### `list_calls`
列出您的账户最近拨打的电话（最近的优先）。
**输入：**
| 字段 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `limit` | 数字 | 否 | 要返回的最大调用数（默认为 20，最多 100） |
**返回：** `{ calls: [ { id, to, objective, status, summary, createdAt, startedAt, endedAt, durationSec, error? } ] }`
## 调用状态
| 状态 | 终端？ | 含义 |
|---|---|---|
| `queued` | 否 | 调用已接受，尚未拨号 |
| `ringing` | 否 | 拨打目标号码 |
| `in_progress` | 否 | 调用正在进行 |
| `completed` | 是 | 调用正常结束 |
| `no_answer` | 是 | 目标号码无人接听 |
| `voicemail` | 是 | 进入语音信箱 |
| `declined` | 是 | 调用被拒绝 |
| `failed` | 是 | 技术故障 |
## 拨打您的第一个电话
1. 配置您的 MCP 客户端，如上所述。
2. 询问您的助手：“拨打 +14155550123，目标是确认明天下午 2 点的会议时间。”
3. 助手调用 `place_call` 并获得一个 `callId`。
4. 询问：“检查调用 `<callId>` -- 是否已完成？”
5. 助手调用 `get_call` 并返回状态、摘要和任何提取的字段。
## 安全
出站目标在服务器端进行筛选（阻止高风险路由，如高费率、卫星），调用时如有要求会携带 AI 披露，放置调用的工具会标注 `openWorldHint: true`，以便客户端在拨打前请求确认。详情：https://voxplo.ai/security
## 开发
运行测试：
```bash
node --test
```
烟雾测试（使用虚拟密钥，应在 stderr 中打印“ready on stdio”）：
```bash
VOXPLO_API_KEY=bys_ak_test node src/server.js
```
## 链接
- Voxplo：https://voxplo.ai
- 代理 API 参考：https://voxplo.ai/docs/agent-api
- OpenAPI 规范：https://www.voxplo.ai/openapi.json
- 托管 MCP 服务器卡：https://mcp.voxplo.ai/.well-known/mcp/server-card.json
- 许可证：MIT
