MCP Server

개요

BotBell MCP Server를 사용하면 AI 어시스턴트가 iPhone과 Mac으로 푸시 알림을 보내고 답장을 읽을 수 있습니다. 구성 후 AI가 할 수 있는 것:

• 알림 전송 — 작업 결과, 경고, 리마인더, 질문
• 답장 읽기 — BotBell 앱에서 답장하면 AI가 읽고 계속 실행
• Bot 관리 — Bot 목록 조회 및 생성 (PAT 모드 전용)

사전 요구 사항

1. iPhone 또는 Mac에 BotBell 앱 설치
2. Bot을 생성하고 토큰 받기 (Bot Token 또는 PAT)
3. Node.js 18+ 설치

인증 모드

MCP Server는 접두사로 토큰 유형을 자동 감지합니다:

PAT 생성 (권장)

1. BotBell 앱 열기 → 설정 탭
2. "API Keys" 탭 → 오른쪽 상단 "+" 버튼 탭
3. 이름 입력 (예: "Claude Code"), 권한 선택 후 "생성" 탭
4. pak_ 으로 시작하는 토큰 복사 — 한 번만 표시됩니다

설치

npm install -g @botbell/mcp-server

구성

AI 도구의 구성에 BotBell MCP Server를 추가하세요:

Claude Desktop

구성 파일을 편집하세요:

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

단일 명령으로 서버를 추가하세요:

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

추가 토큰 (고급)

여러 계정의 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"
      }
    }
  }
}

추가 토큰 구성 시 botbell_send와 botbell_get_replies에 alias 매개변수가 추가되어 특정 토큰으로 메시지를 전송할 수 있습니다.

Cursor / 기타 MCP 클라이언트

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을 생성합니다.

botbell_send

특정 Bot을 통해 푸시 알림을 보냅니다.

botbell_get_replies

사용자 답장을 확인합니다. 메시지는 가져오면 소비됩니다.

Bot Token 모드 도구

Bot Token (bt_ 접두사) 사용 시 botbell_send와 botbell_get_replies 2개의 도구를 사용할 수 있습니다.

bot_id 파라미터가 필요 없습니다 — 토큰이 단일 Bot에 연결되어 있습니다.

인터랙티브 Actions

AI 에이전트가 메시지에 빠른 답장 버튼을 포함할 수 있습니다. 사용자가 옵션을 선택하거나 사용자 정의 응답을 입력하는 휴먼 인 더 루프 워크플로를 가능하게 합니다 — 모두 푸시 알림에서.

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

상호작용 흐름:

1. AI가 botbell_send를 통해 액션 버튼이 포함된 메시지를 전송
2. 사용자가 버튼이 포함된 푸시 알림을 수신
3. 사용자가 버튼을 탭 (또는 "input" 유형의 경우 사용자 정의 응답 입력)
4. AI가 botbell_get_replies를 통해 action key를 포함한 답장을 읽음

사용 예시

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"