English | 中文

BotBell MCP Server

Let AI assistants send push notifications to your iPhone / Mac.

What it does

After setup, your AI assistant (Claude, Cursor, etc.) can:

• Send you notifications — task results, alerts, reminders push to your phone
• Read your replies — you reply in the BotBell app, AI reads it and continues
• Manage your bots — list, create bots (PAT mode only)

Authentication Modes

BotBell MCP Server supports two token types, auto-detected by prefix:

Token Type	Prefix	Scope	Best For
Bot Token	bt_	Single bot only	Simple setup, one bot
Personal Access Token (PAT)	pak_	All your bots	Multi-bot, full control

Bot Token: Get it from the BotBell app when you create a bot. One token = one bot.

PAT: Create one at BotBell app > Settings > API Keys. One token controls all your bots.

Quick Start

1. Install BotBell app

Download from the App Store, create a Bot, and get your token.

2. Install MCP Server

npm install -g @botbell/mcp-server

3. Configure Claude Desktop

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

Option A: PAT mode (recommended)

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

Option B: Bot Token mode

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

4. Use it

Tell Claude:

• "Send a notification to my phone saying the build is done"
• "Analyze this log file and push the summary to my phone"
• "Check if I have any replies in BotBell"
• "List my bots" (PAT mode)
• "Create a new bot called Deploy Alerts" (PAT mode)

Tools

PAT Mode (pak_ token)

botbell_list_bots

List all your bots. Use this to find the bot_id before sending.

botbell_create_bot

Create a new bot.

Parameter	Required	Description
name	Yes	Bot name (max 50 chars)
description	No	Bot description

botbell_send

Send a push notification via a specific bot.

Parameter	Required	Description
bot_id	Yes	Bot ID (use botbell_list_bots to find)
message	Yes	Message content (max 4096 chars)
title	No	Notification title
url	No	URL to attach (tappable)
image_url	No	Image URL to attach
actions	No	Quick reply buttons (max 5), see Actions

botbell_get_replies

Check for user replies to a specific bot.

Parameter	Required	Description
bot_id	Yes	Bot ID to check
limit	No	Max replies to fetch (default 20)

Bot Token Mode (bt_ token)

botbell_send

Send a push notification.

Parameter	Required	Description
message	Yes	Message content (max 4096 chars)
title	No	Notification title
url	No	URL to attach (tappable)
image_url	No	Image URL to attach
actions	No	Quick reply buttons (max 5), see Actions

botbell_get_replies

Fetch user replies from the BotBell app.

Parameter	Required	Description
limit	No	Max replies to fetch (default 20)

Extra Tokens

If you need to send notifications to bots from multiple accounts, you can configure additional Bot Tokens via the BOTBELL_EXTRA_TOKENS environment variable.

Format: 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"
      }
    }
  }
}

When extra tokens are configured:

• The alias parameter becomes available on botbell_send and botbell_get_replies
• Use alias to route messages through a specific extra token
• In PAT mode, botbell_list_bots shows extra bots alongside your own
• Without alias, the primary token (BOTBELL_TOKEN) is used as default

For Cursor / Other MCP Clients

Add to your MCP config:

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

Actions

Add interactive buttons to your notifications. Users can tap to reply without typing.

{
  "message": "Deploy v2.3 to production?",
  "actions": [
    { "key": "approve", "label": "Yes" },
    { "key": "reject", "label": "No" },
    { "key": "custom", "label": "Other...", "type": "input", "placeholder": "Enter reason" }
  ]
}

Field	Required	Description
key	Yes	Identifier returned when user taps (max 64 chars)
label	Yes	Button text shown to user (max 64 chars)
type	No	"button" (default) or "input" (opens text field)
placeholder	No	Placeholder for input field (max 128 chars)

When the user taps an action, botbell_get_replies returns the action key along with the message content:

[2026-01-15T10:30:00.000Z] [action:approve] Yes

Lightweight Alternatives

If MCP is more than you need:

• SDKs — Call the REST API directly from your code:
  • Python: pip install botbell (PyPI · GitHub)
  • JavaScript: npm install @botbell/sdk (npm · GitHub)
• Agent Skill — One command to install, zero dependencies, works with 30+ AI tools: BotBell Agent Skill

Links

• BotBell Website
• API Documentation
• SDK Documentation
• MCP Setup Guide
• Agent Skill Guide