bluebubbles-mcp
bluebubbles-mcp
BlueBubbles 的 MCP 服务器 — 从任何 MCP 客户端访问 iMessage。
从零构建,除了官方的 mcp SDK 和 httpx 外,不依赖任何第三方 MCP 库。
先决条件
Python 3.11+
一个已运行并启用了 API 访问的 BlueBubbles 服务器
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"
}
}
}
}工具
工具 | 描述 | 注解 |
| 检查服务器连接性 | 只读 |
| 服务器信息和健康状态 | 只读 |
| 按最近活动列出对话 | 只读 |
| 包含参与者的聊天详情 | 只读 |
| 来自聊天的消息 | 只读 |
| 按文本、聊天、时间范围搜索 | 只读 |
| 按 GUID 获取单条消息 | 只读 |
| 所有联系人 | 只读 |
| 按电话/电子邮件查找 | 只读 |
| 检查 iMessage 注册状态 | 只读 |
| 检查 FaceTime 注册状态 | 只读 |
| 列出定时消息 | 只读 |
| 获取所有聊天中过去 N 分钟的消息 | 只读 |
| 获取未读消息的聊天及其最新消息 | 只读 |
| 附件元数据 | 只读 |
| 以 base64 格式下载附件 | 只读 |
| 发送已读回执 | 幂等,开放世界 |
| 将聊天标记为未读(本地) | 幂等 |
| 重命名群聊 | 幂等 |
| 显示正在输入指示器 | 开放世界 |
| 停止显示正在输入指示器 | 开放世界 |
| 发送到现有聊天 | 开放世界 |
| 发送到电话/电子邮件 | 开放世界 |
| 发送文件附件 | 开放世界 |
| 发送 Tapback 反应 | 开放世界 |
| 编辑已发送的消息 | 开放世界 |
| 定时发送消息 | 开放世界 |
| 添加到群聊 | 开放世界 |
| 撤回消息 | 破坏性,开放世界 |
| 从群聊中移除 | 破坏性,开放世界 |
| 离开群聊 | 破坏性,开放世界 |
| 删除对话 | 破坏性,开放世界 |
| 取消定时消息 | 破坏性,开放世界 |
许可证
MIT
Available Tools
33 toolsadd_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_facetimeARead-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_imessageARead-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_chatADestructive
Delete an entire chat conversation. This is irreversible.
Args: chat_guid: The chat GUID to delete.
Inputs: chat_guid (required). Returns: result
delete_scheduled_messageADestructive
Delete a scheduled message.
Args: schedule_id: The ID of the scheduled message to cancel.
Inputs: schedule_id (required). Returns: result
download_attachmentARead-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_infoCRead-onlyIdempotent
Get metadata for an attachment (filename, mime type, size, etc.).
Args: attachment_guid: The attachment GUID.
Inputs: attachment_guid (required). Returns: result
get_chatARead-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_messagesARead-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_contactsARead-onlyIdempotent
Get all contacts from the server.
Inputs: no named parameters. Returns: result
get_messageARead-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_messagesARead-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_infoARead-onlyIdempotent
Get BlueBubbles server info and health status.
Inputs: no named parameters. Returns: result
get_unread_chatsARead-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_chatBDestructive
Leave a group chat.
Args: chat_guid: The group chat GUID to leave.
Inputs: chat_guid (required). Returns: result
list_chatsARead-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_messagesARead-onlyIdempotent
List all scheduled (future) messages.
Inputs: no named parameters. Returns: result
lookup_contactARead-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_readAIdempotent
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_unreadCIdempotent
Mark a chat as unread.
Args: chat_guid: The chat GUID.
Inputs: chat_guid (required). Returns: result
pingARead-onlyIdempotent
Ping the BlueBubbles server to check connectivity.
Inputs: no named parameters. Returns: result
remove_participantADestructive
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_groupAIdempotent
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_messagesARead-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_messageBDestructive
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
Scored across 33 tools
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.
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.
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.
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
Related MCP Connectors
Send and receive iMessage, SMS, RCS, and WhatsApp, and manage contacts, chats, and numbers.
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Send and read iMessages from your own Mac and Apple ID — drafts, history and contacts.
WhatsApp (Web + Business API), SMS, contacts, and call records via 2Chat's MCP server.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.10MIT
- AlicenseNot gradedqualityDmaintenanceEnables reading and sending iMessages on macOS through MCP, with tools for managing chats, messages, and attachments via AI agents.MIT
- AlicenseNot gradedqualityDmaintenanceEnables reading, sending, and managing iMessage conversations on macOS through MCP.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP agents to send and receive iMessages via BlueBubbles, allowing human-in-the-loop oversight and replies from a phone.MIT