内容
# Bolna MCP 服务器
远程 MCP 服务器（可流式传输的 HTTP）封装了 [Bolna](https://bolna.ai) 语音 AI REST API（`https://api.bolna.ai`）：7 种读取工具，4 种写入工具，TypeScript，通过 `mcp-handler` 在 Vercel 上部署。
**实时地址：[mcp.bolna.ai](https://mcp.bolna.ai)** — 该页面具有相同的连接说明，下面有每个客户端的复制粘贴按钮。
MCP 是一种开放协议，不特定于 Claude — 该服务器适用于任何与 MCP 兼容的客户端：Claude、Codex、Cursor、Windsurf、Zed 等。
在验证工具路径与 Bolna 文档实时版本的一致性时发现的端点修正记录在 [`src/tools/index.ts`](src/tools/index.ts) 文件顶部的注释块中。
## 可用工具
| 工具 | 类型 | 描述 |
|---|---|---|
| `list_agents` | 读取 | 列出账户中的代理（ID、名称、状态、创建时间）。分页。 |
| `get_agent` | 读取 | 通过 ID 获取一个代理的完整配置。 |
| `list_agent_executions` | 读取 | 一个代理的通话历史。分页，默认为最近 7 天。 |
| `get_execution` | 读取 | 一次通话的完整详细信息：转录、状态、费用、电话数据。 |
| `list_phone_numbers` | 读取 | 账户中的电话号码。 |
| `list_batches` | 读取 | 一个代理的通话批次。 |
| `get_user_info` | 读取 | 账户配置文件、钱包余额、并发限制。 |
| `create_agent` | 写入 | 创建一个新的代理。返回其 ID。 |
| `update_agent` | 写入 | 修改现有代理的名称、提示、欢迎消息、Webhook 或语音设置。 |
| `delete_agent` | 写入 | 永久删除一个代理。不可逆。 |
| `start_outbound_call` | 写入 | 从代理发起真正的 outbound 调用。消耗账户余额。 |
## 安装与使用
**前提条件：** 您自己的 Bolna API 密钥（来自 Bolna 仪表盘）。以下每个客户端都需要两样东西：服务器 URL（`https://mcp.bolna.ai/api/mcp`）和该密钥作为 Bearer 令牌。
### Claude 代码
一条命令：
```bash
./scripts/connect.sh
```
或等效的手动操作：
```bash
claude mcp add --transport http bolna https://mcp.bolna.ai/api/mcp \
--header "Authorization: Bearer <您的 BOLNA_API_KEY>" \
--scope user
```
或通过手动编辑 `~/.claude.json`（或 `.mcp.json` 以获取项目范围的副本）：
```json
{
"mcpServers": {
"bolna": {
"type": "http",
"url": "https://mcp.bolna.ai/api/mcp",
"headers": {
"Authorization": "Bearer <您的 BOLNA_API_KEY>"
}
}
}
}
```
### Claude 桌面版
桌面版配置仅理解本地运行（stdio）的服务器，因此要访问具有自定义标头的远程 HTTP 服务器，需要 [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) 桥接器，它在本地运行并代表您转发标头。将以下内容添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"bolna": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.bolna.ai/api/mcp",
"--header",
"Authorization: Bearer <您的 BOLNA_API_KEY>"
]
}
}
}
```
编辑配置后重启 Claude 桌面版。
### Codex CLI
从环境变量读取密钥而不是配置文件：
```bash
export BOLNA_API_KEY="<您的 BOLNA_API_KEY>"
codex mcp add bolna \
--url https://mcp.bolna.ai/api/mcp \
--bearer-token-env-var BOLNA_API_KEY
```
### Cursor
添加到 `.cursor/mcp.json`（项目）或 `~/.cursor/mcp.json`（全局）：
```json
{
"mcpServers": {
"bolna": {
"url": "https://mcp.bolna.ai/api/mcp",
"headers": {
"Authorization": "Bearer <您的 BOLNA_API_KEY>"
}
}
}
}
```
### Windsurf
添加到 `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"bolna": {
"serverUrl": "https://mcp.bolna.ai/api/mcp",
"headers": {
"Authorization": "Bearer <您的 BOLNA_API_KEY>"
}
}
}
}
```
### Zed
添加到 `settings.json`。Zed 目前不支持在标头中插值环境变量，因此密钥直接写入：
```json
{
"context_servers": {
"bolna": {
"url": "https://mcp.bolna.ai/api/mcp",
"headers": {
"Authorization": "Bearer <您的 BOLNA_API_KEY>"
}
}
}
}
```
### 任意其他 MCP 客户端
指向：
```
URL： https://mcp.bolna.ai/api/mcp
标头： Authorization: Bearer <您的 BOLNA_API_KEY>
```
### claude.ai 网页/移动端
目前不支持 — 其自定义连接器 UI 没有个人 Bearer 令牌字段。在真正的 OAuth 落地之前，上述 CLI/配置选项是唯一的自助服务路径。
### 尝试使用
连接后，开始一个新的对话并询问类似的问题：
- "列出我的 Bolna 代理"
- "我的 Bolna 钱包余额是多少？"
- "使用我的 [代理名称] 代理拨打 +1..."
## 身份验证
在连接到此服务器时，将您的 Bolna API 密钥作为 `Authorization` 标头中的 Bearer 令牌传递。对于本地开发，在 `.env` 中设置 `BOLNA_API_KEY` 并省略标头 — 服务器会自动回退到它。
## 本地开发
```bash
npm install
cp .env.example .env # 然后填写 BOLNA_API_KEY
npm run dev # 或：vercel dev
```
MCP 端点在 `http://localhost:3000/api/mcp` 提供服务。
## 部署
在 **Bolna AI** Vercel 团队下部署，映射到 `mcp.bolna.ai`:
```bash
vercel deploy --prod --scope bolna-ai
```
仅当您想要一个服务器范围的测试备用方案时，请将 `BOLNA_API_KEY` 设置为 Vercel 环境变量；生产调用者应通过 Authorization 标头提供自己的密钥。
## 使用 MCP Inspector 测试
```bash
npx @modelcontextprotocol/inspector
```
在 Inspector UI 中，连接：
- **传输：** 可流式传输的 HTTP
- **URL：** `http://localhost:3000/api/mcp`（或您的部署 URL + `/api/mcp`）
- **标头：** `Authorization: Bearer <您的 Bolna API 密钥>`（如果在 `.env` 中设置了 `BOLNA_API_KEY`，则在本地为可选）
然后使用 Inspector 的 "List Tools" 和 "Call Tool" 面板来测试每个工具，输入有效和无效的输入。
## 许可证
[MIT](LICENSE)
