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

Setup

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

Configuration

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"
      }
    }
  }
}

Tools

Tool	Description	Annotations
ping	Check server connectivity	read-only
get_server_info	Server info and health	read-only
list_chats	List conversations by recent activity	read-only
get_chat	Chat details with participants	read-only
get_chat_messages	Messages from a chat	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 by phone/email	read-only
check_imessage	Check iMessage registration	read-only
check_facetime	Check FaceTime registration	read-only
list_scheduled_messages	List future messages	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 attachment as base64	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
start_typing	Show typing indicator	open-world
stop_typing	Stop typing indicator	open-world
send_message	Send to existing chat	open-world
send_message_to_address	Send to phone/email	open-world
send_attachment	Send a file attachment	open-world
send_reaction	Tapback reaction	open-world
edit_message	Edit a sent message	open-world
schedule_message	Schedule a future 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
delete_chat	Delete a conversation	destructive, open-world
delete_scheduled_message	Cancel scheduled message	destructive, open-world

License

MIT