MCP Server

概述

BotBell MCP Server 让 AI 助手向你的 iPhone 和 Mac 发送推送通知并读取回复。配置完成后，你的 AI 可以：

向你发送通知——任务结果、告警、提醒、问题
读取你的回复——你在 BotBell App 中回复，AI 读取后继续执行
管理你的 Bot——列出和创建 Bot（仅 PAT 模式）

前置条件

在 iPhone 或 Mac 上安装 BotBell App
创建一个 Bot 并获取 Token（Bot Token 或 PAT）
本机已安装 Node.js 18+

认证模式

MCP Server 会根据 Token 前缀自动识别类型：

Token 类型	前缀	范围	适用场景
Bot Token	`bt_`	仅单个 Bot	简单配置，单 Bot 场景
PAT	`pak_`	你的所有 Bot	多 Bot、完整控制

创建 PAT（推荐）

打开 BotBell App → 设置标签页
点击「API Keys」→ 点击右上角「+」按钮
输入名称（如「Claude Code」），选择权限，然后点击「创建」
复制以 pak_ 开头的 Token — 仅显示一次

注意： 完整 Token 仅在创建时显示。如果遗失，请撤销后重新创建。

安装

npm install -g @botbell/mcp-server

配置

将 BotBell MCP Server 添加到你的 AI 工具配置中：

Claude Desktop

编辑配置文件：

~/Library/Application Support/Claude/claude_desktop_config.json

PAT 模式（推荐）

{
  "mcpServers": {
    "botbell": {
      "command": "botbell-mcp",
      "env": {
        "BOTBELL_TOKEN": "pak_your_pat_here"
      }
    }
  }
}

Bot Token 模式

{
  "mcpServers": {
    "botbell": {
      "command": "botbell-mcp",
      "env": {
        "BOTBELL_TOKEN": "bt_your_token_here"
      }
    }
  }
}

Claude Code (CLI)

运行一条命令即可添加：

PAT 模式（推荐）

claude mcp add botbell -e BOTBELL_TOKEN=pak_your_pat_here -- botbell-mcp

Bot Token 模式

claude mcp add botbell -e BOTBELL_TOKEN=bt_your_token_here -- botbell-mcp

额外 Token（高级）

如需向多个账号的 Bot 发送通知，可通过 BOTBELL_EXTRA_TOKENS 环境变量配置额外的 Bot Token：

格式：alias1:bt_token1,alias2:bt_token2

{
  "mcpServers": {
    "botbell": {
      "command": "botbell-mcp",
      "env": {
        "BOTBELL_TOKEN": "pak_your_pat_here",
        "BOTBELL_EXTRA_TOKENS": "team-ops:bt_abc123,home:bt_xyz789"
      }
    }
  }
}

配置额外 Token 后，botbell_send 和 botbell_get_replies 工具会新增 alias 参数，用于指定通过哪个 Token 发送消息。

Cursor / Other MCP Clients

添加到你的 MCP 配置中：

{
  "botbell": {
    "command": "botbell-mcp",
    "env": {
      "BOTBELL_TOKEN": "pak_your_pat_here"
    }
  }
}

可用工具

PAT 模式工具

使用 PAT（pak_ 前缀）时，4 个工具全部可用：

`botbell_list_bots`

列出你的所有 Bot。发送前用此查找 bot_id。

`botbell_create_bot`

创建新 Bot。

字段	必填	说明
`name`	是	Bot 名称（最多 50 个字符）
`description`	否	Bot 描述（可选）

`botbell_send`

通过指定 Bot 发送推送通知。

字段	必填	说明
`bot_id`	是	Bot ID（使用 botbell_list_bots 查找）
`message`	是	消息内容（最多 4096 个字符）
`title`	否	通知标题
`url`	否	附加 URL（可点击）
`image_url`	否	附加图片 URL
`summary`	否	长消息的自定义摘要（最多 512 字符）
`format`	否	"text"（默认）或 "markdown" 启用 Markdown 渲染
`actions_description`	否	显示在操作按钮上方的说明文字（最多 256 字符）
`actions`	否	快捷回复按钮（最多 5 个）。支持 button 和 input 类型。

`botbell_get_replies`

获取用户回复。消息获取后即被消费。

字段	必填	说明
`bot_id`	是	要查询回复的 Bot ID
`limit`	否	最大获取数量（默认 20，最大 100）

Bot Token 模式工具

使用 Bot Token（bt_ 前缀）时，2 个工具可用：botbell_send 和 botbell_get_replies。

无需 bot_id 参数——Token 已绑定到单个 Bot。

交互式 Actions

AI 智能体可以在消息中附带快捷回复按钮，实现人机协作流程——用户直接在推送通知中选择选项或输入自定义回复。

发送带 Actions 的消息

{
  "bot_id": "bot_abc123",
  "message": "3 files will be deleted. Proceed?",
  "title": "Confirmation Required",
  "actions": [
    {"key": "confirm", "label": "Yes, delete"},
    {"key": "cancel", "label": "Cancel"},
    {"key": "custom", "label": "Other...", "type": "input", "placeholder": "e.g. delete only the first two"}
  ]
}

交互流程：

AI 通过 botbell_send 发送带按钮的消息
用户收到带按钮的推送通知
用户点击按钮（或为 "input" 类型输入自定义回复）
AI 通过 botbell_get_replies 读取回复，包括 action key

提示： 将 "input" 类型用于「其他…」选项。当预定义选项不适用时，用户可以输入自由文本回复——减少来回沟通。

使用示例

用自然语言告诉你的 AI 助手你需要什么：

发送通知

"Send a notification to my phone saying the build succeeded"

带按钮提问

"Ask me whether to deploy v2.3.0 to production, with approve/reject buttons and an option to type a custom response"

查看回复

"Check if I have any replies in BotBell"

管理 Bot（仅 PAT）

"List my bots" / "Create a new bot called Deploy Alerts"

支持的平台

Claude Desktop
Claude Code (CLI)
Cursor
Windsurf
任何兼容 MCP 的 AI 工具