MCP Server

Visão Geral

O BotBell MCP Server permite que assistentes de IA enviem notificações push para seu iPhone e Mac, e leiam suas respostas. Uma vez configurado, sua IA pode:

• Enviar notificações — resultados de tarefas, alertas, lembretes, perguntas
• Ler suas respostas — você responde no app BotBell, a IA lê e continua
• Gerenciar seus bots — listar e criar bots (apenas modo PAT)

Pré-requisitos

1. Instale o app BotBell no seu iPhone ou Mac
2. Crie um bot e obtenha seu token (Bot Token ou PAT)
3. Node.js 18+ instalado na sua máquina

Modos de Autenticação

O MCP Server detecta automaticamente o tipo de token pelo prefixo:

Criar um PAT (recomendado)

1. Abrir o app BotBell → aba Configurações
2. Tocar em "API Keys" → tocar no botão "+"
3. Inserir um nome (ex. "Claude Code"), selecionar permissões e tocar em "Criar"
4. Copiar o token que começa com pak_ — exibido apenas uma vez

Instalação

npm install -g @botbell/mcp-server

Configuração

Adicione o BotBell MCP Server à configuração da sua ferramenta de IA:

Claude Desktop

Edite o arquivo de configuração:

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

Execute um único comando para adicionar o servidor:

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 extras (Avançado)

Para enviar notificações para Bots de múltiplas contas, configure Bot Tokens adicionais pela variável BOTBELL_EXTRA_TOKENS:

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

Com tokens extras configurados, um parâmetro alias fica disponível em botbell_send e botbell_get_replies para enviar mensagens por um token específico.

Cursor / Other MCP Clients

Adicione à sua configuração MCP:

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

Ferramentas Disponíveis

Ferramentas do Modo PAT

Ao usar um PAT (prefixo pak_), todas as 4 ferramentas estão disponíveis:

botbell_list_bots

Listar todos os seus bots. Use para encontrar o bot_id antes de enviar.

botbell_create_bot

Criar um novo bot.

botbell_send

Enviar uma notificação push por um bot específico.

botbell_get_replies

Verificar respostas do usuário. As mensagens são consumidas ao buscar.

Ferramentas do Modo Bot Token

Ao usar um Bot Token (prefixo bt_), 2 ferramentas estão disponíveis: botbell_send e botbell_get_replies.

Não é necessário o parâmetro bot_id — o token está vinculado a um único bot.

Actions Interativas

Agentes de IA podem incluir botões de resposta rápida nas mensagens. Isso possibilita fluxos de trabalho com humano-no-loop onde o usuário escolhe uma opção ou digita uma resposta personalizada — tudo a partir de uma notificação 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"}
  ]
}

O fluxo de interação:

1. A IA envia uma mensagem com botões de ação via botbell_send
2. O usuário recebe uma notificação push com os botões
3. O usuário toca em um botão (ou digita uma resposta personalizada para type "input")
4. A IA lê a resposta via botbell_get_replies, incluindo a chave da ação

Exemplos de Uso

Basta dizer ao seu assistente de IA o que você precisa em linguagem natural:

Enviar uma Notificação

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

Perguntar com Botões de Ação

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

Verificar Respostas

"Check if I have any replies in BotBell"

Gerenciar Bots (apenas PAT)

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