bluebubbles-mcp
bluebubbles-mcp
MCP-сервер для BlueBubbles — доступ к iMessage из любого MCP-клиента.
Создан с нуля без сторонних MCP-зависимостей, кроме официального SDK mcp и httpx.
Предварительные требования
Python 3.11+
Запущенный сервер BlueBubbles с включенным API-доступом
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 | только для чтения |
| Все контакты | только для чтения |
| Поиск по телефону/email | только для чтения |
| Проверка регистрации в iMessage | только для чтения |
| Проверка регистрации в FaceTime | только для чтения |
| Список запланированных сообщений | только для чтения |
| Сообщения за последние N минут во всех чатах | только для чтения |
| Чаты с непрочитанными сообщениями + их последние сообщения | только для чтения |
| Метаданные вложения | только для чтения |
| Скачивание вложения в формате base64 | только для чтения |
| Отправить уведомление о прочтении | идемпотентный, open-world |
| Пометить чат как непрочитанный (локально) | идемпотентный |
| Переименовать групповой чат | идемпотентный |
| Показать индикатор набора текста | open-world |
| Остановить индикатор набора текста | open-world |
| Отправить в существующий чат | open-world |
| Отправить на номер телефона/email | open-world |
| Отправить файловое вложение | open-world |
| Реакция Tapback | open-world |
| Редактировать отправленное сообщение | open-world |
| Запланировать сообщение на будущее | open-world |
| Добавить в групповой чат | open-world |
| Отозвать сообщение | деструктивный, open-world |
| Удалить из группового чата | деструктивный, open-world |
| Покинуть групповой чат | деструктивный, open-world |
| Удалить переписку | деструктивный, open-world |
| Отменить запланированное сообщение | деструктивный, open-world |
Лицензия
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