MCP Server

Présentation

Le MCP Server BotBell permet aux assistants IA d'envoyer des notifications push sur votre iPhone et Mac, et de lire vos réponses. Une fois configuré, votre IA peut :

• Vous envoyer des notifications — résultats de tâches, alertes, rappels, questions
• Lire vos réponses — vous répondez dans l'app BotBell, l'IA les lit et continue
• Gérer vos bots — lister et créer des bots (mode PAT uniquement)

Prérequis

1. Installer l'app BotBell sur votre iPhone ou Mac
2. Créer un bot et obtenir votre token (Bot Token ou PAT)
3. Node.js 18+ installé sur votre machine

Modes d'authentification

Le MCP Server détecte automatiquement le type de token par son préfixe :

Créer un PAT (recommandé)

1. Ouvrir l'app BotBell → onglet Réglages
2. Appuyer sur « API Keys » → appuyer sur le bouton « + »
3. Entrer un nom (ex. « Claude Code »), sélectionner les permissions, puis appuyer sur « Créer »
4. Copier le token commençant par pak_ — il n'est affiché qu'une seule fois

Installation

npm install -g @botbell/mcp-server

Configuration

Ajoutez le MCP Server BotBell à la configuration de votre outil IA :

Claude Desktop

Modifiez le fichier de configuration :

~/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)

Exécutez une seule commande pour ajouter le serveur :

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

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

Tokens supplémentaires (Avancé)

Pour envoyer des notifications aux Bots de plusieurs comptes, configurez des Bot Tokens supplémentaires via la variable BOTBELL_EXTRA_TOKENS :

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

Avec des tokens supplémentaires, un paramètre alias devient disponible sur botbell_send et botbell_get_replies pour envoyer via un token spécifique.

Cursor / Autres clients MCP

Ajoutez à votre configuration MCP :

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

Outils disponibles

Outils du mode PAT

Avec un PAT (préfixe pak_), les 4 outils sont disponibles :

botbell_list_bots

Lister tous vos bots. Utilisez ceci pour trouver le bot_id avant d'envoyer.

botbell_create_bot

Créer un nouveau bot.

botbell_send

Envoyer une notification push via un bot spécifique.

botbell_get_replies

Vérifier les réponses de l'utilisateur. Les messages sont consommés lors de la récupération.

Outils du mode Bot Token

Avec un Bot Token (préfixe bt_), 2 outils sont disponibles : botbell_send et botbell_get_replies.

Pas besoin du paramètre bot_id — le token est lié à un seul bot.

Actions interactives

Les agents IA peuvent inclure des boutons de réponse rapide avec les messages. Cela permet des workflows humain-dans-la-boucle où l'utilisateur choisit une option ou saisit une réponse personnalisée — le tout depuis une notification push.

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

Le flux d'interaction :

1. L'IA envoie un message avec des boutons d'action via botbell_send
2. L'utilisateur reçoit une notification push avec les boutons
3. L'utilisateur appuie sur un bouton (ou saisit une réponse personnalisée pour le type "input")
4. L'IA lit la réponse via botbell_get_replies, y compris la clé d'action

Exemples d'utilisation

Dites simplement à votre assistant IA ce dont vous avez besoin en langage naturel :

Envoyer une notification

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

Poser une question avec des boutons d'action

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

Vérifier les réponses

"Check if I have any replies in BotBell"

Gérer les bots (PAT uniquement)

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