bluebubbles-mcp
One line: bluebubbles-mcp exposes an MCP interface for reading and sending iMessages/SMS through a BlueBubbles server, with guardrails (write allowlist, per-agent freshness checks, Private-API detection) baked in.
Connectivity/health:
ping,get_server_info.Browse chats:
list_chats,get_chat,get_unread_chats.Read messages:
get_chat_messages,get_recent_messages,search_messages,get_message.Contacts & lookups:
get_contacts,lookup_contact,check_imessage,check_facetime.Send:
send_message(existing chat),send_message_to_address(new 1:1),send_attachment(base64 file),send_reaction(tapback).Modify messages:
edit_message,unsend_message.Group management:
rename_group,add_participant,remove_participant,leave_chat,delete_chat.Presence/receipts:
start_typing,stop_typing,mark_chat_read,mark_chat_unread.Scheduled messages:
list_scheduled_messages,schedule_message,delete_scheduled_message.Attachments:
get_attachment_info,download_attachment(base64).Safety/config behaviors (from README): write-recipient allowlist enforced server-side, per-agent freshness guard blocking sends after stale reads, Private-API auto-detection hiding unsupported tools, contact-name enrichment, compact responses with
extended=trueopt-in, and stdio or Streamable HTTP (Docker) transport. Note the README also lists additional tools (e.g.find_contact,get_my_address,create_group_chat, alias tools) not present in this schema.
Provides access to iMessage via a BlueBubbles server, allowing for listing and searching chats, sending and editing messages, managing contacts, and performing group chat operations like adding or removing participants.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bluebubbles-mcp Send a message to John saying I'll be there in 5 minutes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Python 3.11+
A running BlueBubbles server with API access enabled
Related MCP server: imessage-mcp
Setup
git clone https://github.com/metaember/bluebubbles-mcp.git
cd bluebubbles-mcp
uv syncConfiguration
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 numbersBehavior:
Unset → unrestricted (backward compatible). Set but empty (
"") → deny all, a safe failure mode.Numbers are matched in normalized E.164 form, so
(555) 123-4567and+15551234567are 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. ABLUEBUBBLES_READ_ALLOWLISTmay 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_messageworks 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.comContact 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: enabledfind_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_messagesrecords the watermark. Only that tool records — a scan likeget_unread_chatsdoesn'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. Seedocs/canonical-chat-identity.md.Trusted archival indexers can use the separately permissionable read-only
list_chat_aliasesandget_chat_alias_messagestools 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-agentagentIdthe caller stamps into request_meta. Required only behind a pooling proxy/airlock, where every agent shares one transport session sosessioncan't distinguish them. Seedocs/freshness-guard.mdfor 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 |
| Check server connectivity | read-only |
| Server info and health | read-only |
| The user's own iMessage address (to identify their own messages) | read-only |
| List conversations by recent activity | read-only |
| Physical chat rows for trusted archival indexers | read-only |
| Chat details with participants | read-only |
| Messages from a chat | read-only |
| Messages from one exact physical chat row | read-only |
| Search by text, chat, time range | read-only |
| Single message by GUID | read-only |
| All contacts | read-only |
| Look up name by phone/email | read-only |
| Find contacts by name (phone/email unknown) | read-only |
| Find chats involving a contact by name | read-only |
| Check iMessage registration | read-only |
| Check FaceTime registration | read-only |
| List/search known handles | read-only |
| Get a handle by address | read-only |
| Contact's Focus / Do Not Disturb status | read-only |
| Find My — your devices' locations | read-only |
| Find My — friends' locations | read-only |
| List future messages | read-only |
| Get one scheduled message by ID | read-only |
| Messages from last N minutes across all chats | read-only |
| Chats with unread messages + their latest messages | read-only |
| Attachment metadata | read-only |
| Download as an MCP image or embedded binary resource (50 MiB max) | read-only |
| Download a group chat's icon | read-only |
| Send read receipt | idempotent, open-world |
| Mark chat unread (local) | idempotent |
| Rename a group chat | idempotent |
| Set a group chat's icon | idempotent |
| Show typing indicator | open-world |
| Stop typing indicator | open-world |
| Send to an existing chat (1:1 or group) | open-world |
| Start a new 1:1 conversation by phone/email | open-world |
| Create a group chat + first message | open-world |
| Send a file attachment | open-world |
| Send text + attachments as one message | open-world |
| Tapback reaction | open-world |
| Edit a sent message | open-world |
| Schedule a future message | open-world |
| Update a scheduled message | open-world |
| Add to group chat | open-world |
| Retract a message | destructive, open-world |
| Remove from group chat | destructive, open-world |
| Leave a group chat | destructive, open-world |
| Remove a group chat's icon | destructive, open-world |
| Delete a single message | destructive, open-world |
| Delete a conversation | destructive, open-world |
| 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-mcpAs 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-stoppedNotes:
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_URLmust be reachable from inside the container — use a hostname/IP the container can resolve (e.g. the BlueBubbles host's LAN address orhost.docker.internal), notlocalhost.
License
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