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 工具