bluebubbles-mcp

BlueBubbles용 MCP 서버 — 모든 MCP 클라이언트에서 iMessage에 액세스하세요.

공식 mcp SDK 및 httpx 외에 타사 MCP 종속성 없이 처음부터 새로 구축되었습니다.

필수 조건

Python 3.11+
API 액세스가 활성화된 실행 중인 BlueBubbles 서버

설정

git clone https://github.com/metaember/bluebubbles-mcp.git
cd bluebubbles-mcp
uv sync

구성

MCP 클라이언트 구성(예: Claude Code ~/.claude/settings.json)에 추가하세요:

{
  "mcpServers": {
    "bluebubbles": {
      "command": "uv",
      "args": ["--directory", "/path/to/bluebubbles-mcp", "run", "python", "-m", "bb_mcp.server"],
      "env": {
        "BLUEBUBBLES_URL": "https://your-bluebubbles-server",
        "BLUEBUBBLES_PASSWORD": "your-server-password"
      }
    }
  }
}

도구

도구	설명	주석
`ping`	서버 연결 확인	읽기 전용
`get_server_info`	서버 정보 및 상태	읽기 전용
`list_chats`	최근 활동별 대화 목록	읽기 전용
`get_chat`	참가자가 포함된 채팅 세부 정보	읽기 전용
`get_chat_messages`	채팅 메시지	읽기 전용
`search_messages`	텍스트, 채팅, 시간 범위별 검색	읽기 전용
`get_message`	GUID별 단일 메시지	읽기 전용
`get_contacts`	모든 연락처	읽기 전용
`lookup_contact`	전화번호/이메일로 조회	읽기 전용
`check_imessage`	iMessage 등록 확인	읽기 전용
`check_facetime`	FaceTime 등록 확인	읽기 전용
`list_scheduled_messages`	예약된 메시지 목록	읽기 전용
`get_recent_messages`	모든 채팅에서 지난 N분간의 메시지	읽기 전용
`get_unread_chats`	읽지 않은 메시지가 있는 채팅 및 최신 메시지	읽기 전용
`get_attachment_info`	첨부 파일 메타데이터	읽기 전용
`download_attachment`	첨부 파일을 base64로 다운로드	읽기 전용
`mark_chat_read`	읽음 확인 전송	멱등성, 오픈 월드
`mark_chat_unread`	채팅을 읽지 않음으로 표시 (로컬)	멱등성
`rename_group`	그룹 채팅 이름 변경	멱등성
`start_typing`	입력 중 표시	오픈 월드
`stop_typing`	입력 중 표시 중지	오픈 월드
`send_message`	기존 채팅으로 전송	오픈 월드
`send_message_to_address`	전화번호/이메일로 전송	오픈 월드
`send_attachment`	파일 첨부 전송	오픈 월드
`send_reaction`	탭백(Tapback) 반응	오픈 월드
`edit_message`	전송된 메시지 편집	오픈 월드
`schedule_message`	메시지 예약	오픈 월드
`add_participant`	그룹 채팅에 추가	오픈 월드
`unsend_message`	메시지 취소	파괴적, 오픈 월드
`remove_participant`	그룹 채팅에서 제거	파괴적, 오픈 월드
`leave_chat`	그룹 채팅 나가기	파괴적, 오픈 월드
`delete_chat`	대화 삭제	파괴적, 오픈 월드
`delete_scheduled_message`	예약된 메시지 취소	파괴적, 오픈 월드