bluebubbles-mcp

BlueBubbles 的 MCP 服务器 — 从任何 MCP 客户端访问 iMessage。

从零构建，除了官方的 mcp SDK 和 httpx 外，不依赖任何第三方 MCP 库。

先决条件

Python 3.11+
一个已运行并启用了 API 访问的 BlueBubbles 服务器

设置

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`	按电话/电子邮件查找	只读
`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`	发送已读回执	幂等，开放世界
`mark_chat_unread`	将聊天标记为未读（本地）	幂等
`rename_group`	重命名群聊	幂等
`start_typing`	显示正在输入指示器	开放世界
`stop_typing`	停止显示正在输入指示器	开放世界
`send_message`	发送到现有聊天	开放世界
`send_message_to_address`	发送到电话/电子邮件	开放世界
`send_attachment`	发送文件附件	开放世界
`send_reaction`	发送 Tapback 反应	开放世界
`edit_message`	编辑已发送的消息	开放世界
`schedule_message`	定时发送消息	开放世界
`add_participant`	添加到群聊	开放世界
`unsend_message`	撤回消息	破坏性，开放世界
`remove_participant`	从群聊中移除	破坏性，开放世界
`leave_chat`	离开群聊	破坏性，开放世界
`delete_chat`	删除对话	破坏性，开放世界
`delete_scheduled_message`	取消定时消息	破坏性，开放世界