Skip to main content
Glama
bluebubbles-mcp

bluebubbles-mcp

by charlesbine

bluebubbles-mcp

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

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

필수 조건

Related MCP server: imessage-mcp

설정

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

예약된 메시지 취소

파괴적, 오픈 월드

라이선스

MIT

Available Tools

33 tools
add_participantA

Add a participant to a group chat.

Args: chat_guid: The group chat GUID. address: Phone number or email of the person to add.

Inputs: chat_guid (required), address (required). Returns: result

check_facetimeA
Read-onlyIdempotent

Check if a phone number or email is registered for FaceTime.

Args: address: Phone number or email to check.

Inputs: address (required). Returns: result

check_imessageA
Read-onlyIdempotent

Check if a phone number or email is registered for iMessage.

Args: address: Phone number or email to check.

Inputs: address (required). Returns: result

delete_chatA
Destructive

Delete an entire chat conversation. This is irreversible.

Args: chat_guid: The chat GUID to delete.

Inputs: chat_guid (required). Returns: result

delete_scheduled_messageA
Destructive

Delete a scheduled message.

Args: schedule_id: The ID of the scheduled message to cancel.

Inputs: schedule_id (required). Returns: result

download_attachmentA
Read-onlyIdempotent

Download an attachment and return it as base64-encoded data.

Args: attachment_guid: The attachment GUID.

Inputs: attachment_guid (required). Returns: result

edit_messageB

Edit a previously sent message.

Args: message_guid: GUID of the message to edit. new_text: The new message text.

Inputs: message_guid (required), new_text (required). Returns: result

get_attachment_infoC
Read-onlyIdempotent

Get metadata for an attachment (filename, mime type, size, etc.).

Args: attachment_guid: The attachment GUID.

Inputs: attachment_guid (required). Returns: result

get_chatA
Read-onlyIdempotent

Get details for a specific chat, including participants.

Args: chat_guid: The chat GUID (e.g. 'iMessage;-;+15551234567' or 'iMessage;+;chat123').

Inputs: chat_guid (required). Returns: result

get_chat_messagesA
Read-onlyIdempotent

Get messages from a specific chat.

Args: chat_guid: The chat GUID. limit: Max messages to return (default 25). offset: Pagination offset. sort: 'ASC' or 'DESC' (default DESC = newest first). after: Only messages after this epoch-ms timestamp. before: Only messages before this epoch-ms timestamp.

Inputs: chat_guid (required), limit, offset, sort, +2 more. Returns: result

get_contactsA
Read-onlyIdempotent

Get all contacts from the server.

Inputs: no named parameters. Returns: result

get_messageA
Read-onlyIdempotent

Get a single message by its GUID, including chat and attachment info.

Args: message_guid: The message GUID.

Inputs: message_guid (required). Returns: result

get_recent_messagesA
Read-onlyIdempotent

Get recent messages across all chats within a time window.

Args: minutes: How far back to look (default 60 minutes). limit: Max messages to return (default 50).

Inputs: minutes, limit. Returns: result

get_server_infoA
Read-onlyIdempotent

Get BlueBubbles server info and health status.

Inputs: no named parameters. Returns: result

get_unread_chatsA
Read-onlyIdempotent

Get all chats with unread messages, including their latest messages.

Args: message_limit: Number of recent messages to include per unread chat (default 5).

Inputs: message_limit. Returns: result

leave_chatB
Destructive

Leave a group chat.

Args: chat_guid: The group chat GUID to leave.

Inputs: chat_guid (required). Returns: result

list_chatsA
Read-onlyIdempotent

List iMessage conversations, sorted by most recent activity.

Args: limit: Max number of chats to return (default 25). offset: Pagination offset.

Inputs: limit, offset. Returns: result

list_scheduled_messagesA
Read-onlyIdempotent

List all scheduled (future) messages.

Inputs: no named parameters. Returns: result

lookup_contactA
Read-onlyIdempotent

Look up contacts by phone numbers or email addresses.

Args: addresses: List of phone numbers or emails to look up.

Inputs: addresses (required). Returns: result

mark_chat_readA
Idempotent

Mark a chat as read (sends read receipt visible to the other person).

Args: chat_guid: The chat GUID.

Inputs: chat_guid (required). Returns: result

mark_chat_unreadC
Idempotent

Mark a chat as unread.

Args: chat_guid: The chat GUID.

Inputs: chat_guid (required). Returns: result

pingA
Read-onlyIdempotent

Ping the BlueBubbles server to check connectivity.

Inputs: no named parameters. Returns: result

remove_participantA
Destructive

Remove a participant from a group chat.

Args: chat_guid: The group chat GUID. address: Phone number or email of the person to remove.

Inputs: chat_guid (required), address (required). Returns: result

rename_groupA
Idempotent

Rename a group chat.

Args: chat_guid: The group chat GUID. name: New display name for the group.

Inputs: chat_guid (required), name (required). Returns: result

schedule_messageA

Schedule a message to be sent at a future time.

Args: chat_guid: The chat GUID to send to. message: The message text. scheduled_for: When to send, as epoch milliseconds.

Inputs: chat_guid (required), message (required), scheduled_for (required). Returns: result

search_messagesA
Read-onlyIdempotent

Search messages by text content and/or filter by chat and time range.

Args: query: Text to search for in message bodies. chat_guid: Limit search to a specific chat. limit: Max results (default 25). offset: Pagination offset. after: Only messages after this epoch-ms timestamp. before: Only messages before this epoch-ms timestamp.

Inputs: query, chat_guid, limit, offset, +2 more. Returns: result

send_attachmentA

Send a file attachment to a chat.

Args: chat_guid: The chat GUID to send to. data_base64: The file contents as a base64-encoded string. filename: The filename (e.g. 'photo.jpg'). mime_type: MIME type (e.g. 'image/jpeg'). Defaults to 'application/octet-stream'.

Inputs: chat_guid (required), data_base64 (required), filename (required), mime_type. Returns: result

send_messageA

Send a text message to an existing chat.

Args: chat_guid: The chat GUID to send to. message: The message text. reply_to_guid: Optional message GUID to reply to (creates a thread).

Inputs: chat_guid (required), message (required), reply_to_guid. Returns: result

send_message_to_addressA

Send a message to a phone number or email, creating a new chat if needed.

Args: address: Phone number (e.g. '+15551234567') or email address. message: The message text. service: 'iMessage' or 'SMS' (default iMessage).

Inputs: address (required), message (required), service. Returns: result

send_reactionA

Send a tapback reaction to a message.

Args: chat_guid: The chat GUID containing the message. message_guid: The GUID of the message to react to. reaction: One of: love, like, dislike, laugh, emphasize, question. Prefix with '-' to remove (e.g. '-love').

Inputs: chat_guid (required), message_guid (required), reaction (required). Returns: result

start_typingB

Show a typing indicator in a chat (visible to the other person).

Args: chat_guid: The chat GUID.

Inputs: chat_guid (required). Returns: result

stop_typingC

Stop the typing indicator in a chat.

Args: chat_guid: The chat GUID.

Inputs: chat_guid (required). Returns: result

unsend_messageB
Destructive

Unsend (retract) a previously sent message.

Args: message_guid: GUID of the message to unsend.

Inputs: message_guid (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 33 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose. Sending tools are differentiated by target (existing chat vs. new address), type (text, attachment, reaction), and timing (immediate vs. scheduled). No overlapping functionality.

    Naming Consistency5/5

    Tool names consistently follow a verb_noun pattern (e.g., send_message, get_chat, delete_chat). Minor variations like 'check_facetime' and 'mark_chat_unread' are still consistent in structure.

    Tool Count4/5

    33 tools is above average but appropriate for a comprehensive iMessage server covering messaging, attachments, reactions, scheduling, participants, contacts, and typing indicators. Each tool serves a unique function.

    Completeness5/5

    The tool set covers the full lifecycle of messaging: send, receive, edit, unsend, schedule, react, manage participants, handle attachments, search, and check user availability. No obvious gaps for core iMessage operations.

    Maintenance

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables reading, searching, and sending iMessages directly from MCP-compatible clients by accessing the local macOS iMessage database, supporting conversations, attachments, and both individual and group chats.
      10
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables reading and sending iMessages on macOS through MCP, with tools for managing chats, messages, and attachments via AI agents.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables reading, sending, and managing iMessage conversations on macOS through MCP.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP agents to send and receive iMessages via BlueBubbles, allowing human-in-the-loop oversight and replies from a phone.
      MIT