Skip to main content
Glama
bluebubbles-mcp

bluebubbles-mcp

by charlesbine

bluebubbles-mcp

MCP server for BlueBubbles — access iMessage from any MCP client.

Built from scratch with no third-party MCP dependencies beyond the official mcp SDK and httpx.

Prerequisites

Related MCP server: imessage-mcp

Setup

git clone https://github.com/metaember/bluebubbles-mcp.git
cd bluebubbles-mcp
uv sync

Configuration

BlueBubbles authenticates REST requests with a password query parameter. The MCP client does not forward HTTP exception text or provider error messages: those can contain the full request URL and its credential. Tool errors report the HTTP or API status, or a generic transport failure, instead. The server also disables httpx/httpcore request logging because it can include that URL.

Add to your MCP client config (e.g. 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"
      }
    }
  }
}

Restricting write recipients (allowlist)

By default the server can message anyone. Set BLUEBUBBLES_WRITE_ALLOWLIST to a comma-separated list of phone numbers and/or emails to restrict every write (send, reaction, attachment, typing, scheduling, group edits, delete/leave) to those recipients. It is enforced server-side, so an MCP client — including one reaching the HTTP transport — cannot bypass it.

"BLUEBUBBLES_WRITE_ALLOWLIST": "+15551234567, partner@example.com",
"BLUEBUBBLES_ALLOWLIST_REGION": "US"  // optional, default region for parsing local numbers

Behavior:

  • Unset → unrestricted (backward compatible). Set but empty ("") → deny all, a safe failure mode.

  • Numbers are matched in normalized E.164 form, so (555) 123-4567 and +15551234567 are equivalent; emails match case-insensitively.

  • For a group chat, every participant must be on the list or the write is blocked. A chat whose participants can't be resolved is denied (fail-closed).

  • Read tools are not restricted, and the message-GUID writes (edit_message, unsend_message) aren't covered — they only act on an already-sent message and can't reach a new recipient. A BLUEBUBBLES_READ_ALLOWLIST may be added later.

Private API vs AppleScript

BlueBubbles can drive Messages two ways. AppleScript works on any install with no extra setup but only sends plain texts/attachments. The Private API (requires the BlueBubbles Helper + partially disabled SIP) additionally unlocks tapbacks, edit/unsend, typing indicators, read receipts, group management, threaded replies, and SMS sending.

On startup the server reads /server/info and adapts itself to what's actually available:

  • Sends use the Private API when present, and fall back to AppleScript when not — so send_message works on a bare install instead of erroring.

  • Tools that require the Private API (reactions, edit/unsend, typing, read receipts, group management, iMessage/FaceTime availability checks) are hidden from the tool list when it's unavailable, so a client never sees a tool that could only fail.

Override the auto-detection with BLUEBUBBLES_PRIVATE_API:

"BLUEBUBBLES_PRIVATE_API": "auto"   // default: introspect /server/info
// "true"  — force-enable (assume the Private API is set up)
// "false" — force-disable (AppleScript only; hide Private API tools)

If /server/info can't be read at startup, detection fails open (assumes the Private API is available) so a transient blip doesn't hide half the toolset.

The same /server/info read also discovers the user's own iMessage address, surfaced by the get_my_address tool. Override it if detection is wrong or you run multiple handles:

"BLUEBUBBLES_MY_ADDRESS": "+15551234567"  // or you@icloud.com

Contact names

Message and chat data from BlueBubbles carries raw phone numbers and emails, not names. To save the model from constantly cross-referencing numbers, read responses are enriched with a contactName beside each handle, and find_contact / find_chats let it reach people by name instead of number.

Resolution is lazy and cached per session: a response's addresses are looked up in a single batched /contact/query the first time they're seen, then reused. Disable it (for leaner responses or if your contact DB is slow) with:

"BLUEBUBBLES_RESOLVE_NAMES": "false"  // default: enabled

find_contact / find_chats still work when this is off — they're explicit.

Freshness guard

An agent can reply to a conversation against a stale snapshot — it read the thread a while ago, a new message arrived in the gap, and it answers without seeing it. The freshness guard enforces, server-side and per agent, that a send into a chat only goes through if that agent read the chat within the last hour and nothing new has arrived since. (A consequence: you must read an existing chat before sending into it — good hygiene for replies. Starting a brand-new conversation via create_chat is unaffected; it's for first contact only and, with the guard on, refuses to reach an existing chat — use send_message for those.)

How it works. The guard keeps a per-agent watermark — the newest message each agent has seen in each chat (optimistic concurrency, like an ETag on the thread):

  • Reading a chat with get_chat_messages records the watermark. Only that tool records — a scan like get_unread_chats doesn't — so to reply you must deliberately open the actual thread.

  • Before a send, the server re-checks the chat's live newest message. If anything (from anyone — the other person, you on another device, or another agent) arrived since your watermark, or your read is older than the TTL, the send is blocked with a note to re-read and re-plan.

  • Your own send advances your watermark, so sending doesn't block your next send.

  • Watermarks key on the resolved chat GUID. Reads and sends resolve known aliases (e.g. a stale iMessageLite;-; shadow) to the live row, while unresolved aliases require their own read. Guarded sends refresh alias selection before sending. See docs/canonical-chat-identity.md.

  • Trusted archival indexers can use the separately permissionable read-only list_chat_aliases and get_chat_alias_messages tools to inspect exact physical rows without changing send freshness; normal agent tools remain canonicalized.

See docs/freshness-guard.md for the full design.

On by default. Disable with BLUEBUBBLES_FRESHNESS=off. Tuning:

"BLUEBUBBLES_FRESHNESS": "off",                  // default: on
"BLUEBUBBLES_FRESHNESS_IDENTITY": "session",     // how agents are told apart (default)
"BLUEBUBBLES_WATERMARK_TTL_SECONDS": "3600",     // how long a read stays "fresh" (default 1h)
"BLUEBUBBLES_WATERMARK_MAX_AGENTS": "10000"      // memory backstop (default 10000)

The freshness check is per agent, so it needs to tell agents apart. BLUEBUBBLES_FRESHNESS_IDENTITY selects how:

  • session (default): use the MCP transport session — automatic and zero-config for stdio (one agent) and direct HTTP (one session per connecting client). Over HTTP this relies on stateful sessions (FastMCP's default); the server refuses to start if you combine session-identity freshness with stateless HTTP, since every send would be blocked.

  • meta: identify agents by a per-agent agentId the caller stamps into request _meta. Required only behind a pooling proxy/airlock, where every agent shares one transport session so session can't distinguish them. See docs/freshness-guard.md for the airlock contract.

Compact responses & sender filtering

Message reads return a compact projection by default — the fields an assistant needs (guid, text, handle + contactName, isFromMe, timestamps, attachment names, reaction/reply linkage) instead of the full raw BlueBubbles objects, which cuts token usage substantially. Pass extended=true on any read tool to get the complete raw fields.

Message reads (get_chat_messages, search_messages, get_recent_messages) also accept from_address to filter by who sent each message — pass a phone number / email, or "me" for the user's own messages. Filtering is by true sender (the user when isFromMe, otherwise the message's handle), so it's correct in both 1:1 and group chats.

Tools

Tool

Description

Annotations

ping

Check server connectivity

read-only

get_server_info

Server info and health

read-only

get_my_address

The user's own iMessage address (to identify their own messages)

read-only

list_chats

List conversations by recent activity

read-only

list_chat_aliases

Physical chat rows for trusted archival indexers

read-only

get_chat

Chat details with participants

read-only

get_chat_messages

Messages from a chat

read-only

get_chat_alias_messages

Messages from one exact physical chat row

read-only

search_messages

Search by text, chat, time range

read-only

get_message

Single message by GUID

read-only

get_contacts

All contacts

read-only

lookup_contact

Look up name by phone/email

read-only

find_contact

Find contacts by name (phone/email unknown)

read-only

find_chats

Find chats involving a contact by name

read-only

check_imessage

Check iMessage registration

read-only

check_facetime

Check FaceTime registration

read-only

query_handles

List/search known handles

read-only

get_handle

Get a handle by address

read-only

get_focus_status

Contact's Focus / Do Not Disturb status

read-only

find_my_devices

Find My — your devices' locations

read-only

find_my_friends

Find My — friends' locations

read-only

list_scheduled_messages

List future messages

read-only

get_scheduled_message

Get one scheduled message by ID

read-only

get_recent_messages

Messages from last N minutes across all chats

read-only

get_unread_chats

Chats with unread messages + their latest messages

read-only

get_attachment_info

Attachment metadata

read-only

download_attachment

Download as an MCP image or embedded binary resource (50 MiB max)

read-only

get_group_icon

Download a group chat's icon

read-only

mark_chat_read

Send read receipt

idempotent, open-world

mark_chat_unread

Mark chat unread (local)

idempotent

rename_group

Rename a group chat

idempotent

set_group_icon

Set a group chat's icon

idempotent

start_typing

Show typing indicator

open-world

stop_typing

Stop typing indicator

open-world

send_message

Send to an existing chat (1:1 or group)

open-world

create_chat

Start a new 1:1 conversation by phone/email

open-world

create_group_chat

Create a group chat + first message

open-world

send_attachment

Send a file attachment

open-world

send_multipart

Send text + attachments as one message

open-world

send_reaction

Tapback reaction

open-world

edit_message

Edit a sent message

open-world

schedule_message

Schedule a future message

open-world

update_scheduled_message

Update a scheduled message

open-world

add_participant

Add to group chat

open-world

unsend_message

Retract a message

destructive, open-world

remove_participant

Remove from group chat

destructive, open-world

leave_chat

Leave a group chat

destructive, open-world

remove_group_icon

Remove a group chat's icon

destructive, open-world

delete_message

Delete a single message

destructive, open-world

delete_chat

Delete a conversation

destructive, open-world

delete_scheduled_message

Cancel scheduled message

destructive, open-world

Run over HTTP (Docker)

The server speaks stdio by default. Set MCP_TRANSPORT=streamable-http to serve over Streamable HTTP instead, so any HTTP-capable MCP client can connect at http://<host>:8000/mcp. The Docker image sets this for you.

docker build -t bluebubbles-mcp .
docker run --rm -e BLUEBUBBLES_URL -e BLUEBUBBLES_PASSWORD -p 8000:8000 bluebubbles-mcp

As a Compose service — credentials live in this container's own environment (an env_file or Docker secrets), so they stay isolated to this tool:

services:
  bluebubbles-mcp:
    build: .
    environment:
      BLUEBUBBLES_URL: ${BLUEBUBBLES_URL}
      BLUEBUBBLES_PASSWORD: ${BLUEBUBBLES_PASSWORD}
    restart: unless-stopped

Notes:

  • The HTTP endpoint is unauthenticated, so don't expose it publicly — keep it on a private/internal network (and drop the published ports: if a co-located client reaches it over the Compose network).

  • BLUEBUBBLES_URL must be reachable from inside the container — use a hostname/IP the container can resolve (e.g. the BlueBubbles host's LAN address or host.docker.internal), not localhost.

License

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