bluebubbles-mcp
bluebubbles-mcp
BlueBubbles 用のMCPサーバー — あらゆるMCPクライアントからiMessageにアクセスできます。
公式の mcp SDKと httpx 以外のサードパーティ製MCP依存関係を使用せず、ゼロから構築されています。
前提条件
Python 3.11以上
APIアクセスが有効な BlueBubblesサーバー が稼働していること
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"
}
}
}
}ツール
ツール | 説明 | アノテーション |
| サーバー接続の確認 | read-only |
| サーバー情報と健全性 | read-only |
| 最近のアクティビティ順に会話をリストアップ | read-only |
| 参加者を含むチャットの詳細 | read-only |
| チャット内のメッセージ | read-only |
| テキスト、チャット、時間範囲による検索 | read-only |
| GUIDによる単一メッセージの取得 | read-only |
| すべての連絡先 | read-only |
| 電話番号/メールアドレスによる検索 | read-only |
| iMessage登録の確認 | read-only |
| FaceTime登録の確認 | read-only |
| 予約済みメッセージのリスト | read-only |
| 全チャットの過去N分間のメッセージ | read-only |
| 未読メッセージがあるチャットと最新メッセージ | read-only |
| 添付ファイルのメタデータ | read-only |
| 添付ファイルをbase64でダウンロード | read-only |
| 既読通知を送信 | idempotent, open-world |
| チャットを未読にする(ローカル) | idempotent |
| グループチャットの名前変更 | idempotent |
| 入力中インジケーターを表示 | open-world |
| 入力中インジケーターを停止 | open-world |
| 既存のチャットに送信 | open-world |
| 電話番号/メールアドレスに送信 | open-world |
| ファイル添付を送信 | open-world |
| タップバックリアクション | open-world |
| 送信済みメッセージの編集 | open-world |
| メッセージの送信予約 | open-world |
| グループチャットに追加 | open-world |
| メッセージの取り消し | destructive, open-world |
| グループチャットから削除 | destructive, open-world |
| グループチャットから退出 | destructive, open-world |
| 会話を削除 | destructive, open-world |
| 予約済みメッセージのキャンセル | destructive, 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