MCP Server

Overview

The BotBell MCP Server lets AI assistants send push notifications to your iPhone and Mac, and read your replies. Once configured, your AI can:

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

Prerequisites

1. Install the BotBell app on your iPhone or Mac
2. Create a bot and get your token (Bot Token or PAT)
3. Node.js 18+ installed on your machine

Authentication Modes

The MCP server auto-detects the token type by its prefix:

Installation

npm install -g @botbell/mcp-server

Configuration

Add the BotBell MCP server to your AI tool's configuration:

Claude Desktop

Edit the config file:

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

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

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

Claude Code (CLI)

Run a single command to add the server:

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

رموز إضافية (متقدم)

لإرسال إشعارات إلى بوتات من حسابات متعددة، قم بتكوين رموز Bot إضافية عبر متغير BOTBELL_EXTRA_TOKENS:

التنسيق: 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"
      }
    }
  }
}

عند تكوين رموز إضافية، تصبح معلمة alias متاحة في botbell_send و botbell_get_replies لتوجيه الرسائل عبر رمز محدد.

Cursor / Other MCP Clients

Add to your MCP configuration:

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

Available Tools

PAT Mode Tools

When using a PAT (pak_ prefix), all 4 tools are available:

botbell_list_bots

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

botbell_create_bot

Create a new bot.

botbell_send

Send a push notification via a specific bot.

botbell_get_replies

Check for user replies. Messages are consumed on fetch.

Bot Token Mode Tools

When using a Bot Token (bt_ prefix), 2 tools are available: botbell_send and botbell_get_replies.

No bot_id parameter needed — the token is tied to a single bot.

Interactive Actions

AI agents can include quick reply buttons with messages. This enables human-in-the-loop workflows where the user picks an option or types a custom response — all from a push notification.

{
  "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"}
  ]
}

The interaction flow:

1. AI sends a message with action buttons via botbell_send
2. User receives a push notification with the buttons
3. User taps a button (or types a custom response for "input" type)
4. AI reads the reply via botbell_get_replies, including the action key

Usage Examples

Just tell your AI assistant what you need in natural language:

Send a Notification

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

Ask with Action Buttons

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

Check for Replies

"Check if I have any replies in BotBell"

Manage Bots (PAT only)

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