Skip to main content
Glama
bluebubbles-mcp

bluebubbles-mcp

by charlesbine

bluebubbles-mcp

MCP-сервер для BlueBubbles — доступ к iMessage из любого MCP-клиента.

Создан с нуля без сторонних MCP-зависимостей, кроме официального SDK mcp и httpx.

Предварительные требования

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

Поиск по телефону/email

только для чтения

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

Отправить уведомление о прочтении

идемпотентный, open-world

mark_chat_unread

Пометить чат как непрочитанный (локально)

идемпотентный

rename_group

Переименовать групповой чат

идемпотентный

start_typing

Показать индикатор набора текста

open-world

stop_typing

Остановить индикатор набора текста

open-world

send_message

Отправить в существующий чат

open-world

send_message_to_address

Отправить на номер телефона/email

open-world

send_attachment

Отправить файловое вложение

open-world

send_reaction

Реакция Tapback

open-world

edit_message

Редактировать отправленное сообщение

open-world

schedule_message

Запланировать сообщение на будущее

open-world

add_participant

Добавить в групповой чат

open-world

unsend_message

Отозвать сообщение

деструктивный, open-world

remove_participant

Удалить из группового чата

деструктивный, open-world

leave_chat

Покинуть групповой чат

деструктивный, open-world

delete_chat

Удалить переписку

деструктивный, open-world

delete_scheduled_message

Отменить запланированное сообщение

деструктивный, open-world

Лицензия

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