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