Mac Messages MCP 是一个本地运行的 MCP 服务器，用于把 macOS「信息」应用中的对话安全地接入支持 MCP 的本地客户端（如 Claude、Codex、Cursor、VS Code 等），让模型可以搜索、读取和发送消息。
用途 它面向需要在 Mac 上查询和分析 iMessage 对话的场景：读取最近消息、按联系人/群聊检索、搜索消息文本与附件元数据、在明确调用时发送文本或文件附件，以及等待新消息。
主要能力
- 读取与搜索消息，读取来自本地 SQLite 数据库（chat.db 与 AddressBook 数据库），以只读方式打开。
- 电话号码校验与区域展开：支持 E.164 与国际/本国格式，本国格式会依据区域转换为 E.164（例如 (415) 555-1234 → +14155551234 美国区，06 39 98 00 01 → +33639980001 法国区）。可用 MAC_MESSAGES_REGION 指定 ISO 3166-1 alpha-2 代码；已是 E.164 的号码不会被重新解释。也接受电子邮件地址、联系人姓名，以及联系人搜索返回的 contact:N 选项。
- 联系人管理与查找：提供 tool_check_addressbook、tool_check_contacts 等工具；tool_create_contact 仅创建新联系人卡片，不编辑或合并已有卡片。
- 群聊处理：先用 tool_get_chats 获取 chat ID，再用 tool_send_message 并设置 group_chat=true 发送；读取同一会话时将同一 ID 作为 chat_id 传给 tool_get_recent_messages。
- 附件处理：分三步——消息读取/搜索会附加如 [attachments: #42 image/jpeg (invitation.jpg)] 的标记；tool_search_attachments 仅搜索元数据；tool_get_attachment 获取指定附件。图片默认内联返回，最大 5 MB，HEIC 转为 PNG；更大的图片、PDF、视频和音频以本地文件路径返回。贴纸、链接预览负载和 .pluginPayloadAttachment 容器会被过滤。
- 消息元数据、分页与游标：tool_get_recent_messages 在页面填满时会给出下一页 offset；传入 since_rowid 会切换为向前游标读取（最旧优先），忽略 hours 窗口，这也是 tool_wait_for_new_messages 轮询所用的方式。
- 内置 MCP 提示：triage_unread_messages、summarize_recent_messages、draft_reply，用于指导代理调用哪些读取工具，且不会发送任何内容。
- MCP 资源：messages://recent/{hours} 与 messages://contact/{contact}/{hours}。
使用方式 需 Python 3.10 或更高版本。可用 uvx 在隔离环境中安装并运行，无需先创建虚拟环境。服务器命令在各客户端一致，配置方式因客户端而异：Claude Desktop 在「设置 → 开发者 → 编辑配置」加入 mcpServers；Claude Code 在用户范围添加一次即可全局可用，并用 /mcp 检查；Codex 客户端共享 MCP 配置，也可直接写入 ~/.codex/config.toml；Cursor 在「设置 → Tools & MCP → New MCP Server」添加；VS Code 通过命令面板「MCP: Add Server」选择 Command (stdio)，命令填 uvx、参数填 mac-messages-mcp，注意 VS Code 使用顶层 servers 对象而 Claude Desktop 与 Cursor 使用 mcpServers。 权限方面：打开「系统设置 → 隐私与安全性 → 完全磁盘访问权限」，为启动 MCP 服务器的应用授权（桌面/IDE 集成通常是 Claude Desktop、Cursor、VS Code 或 ChatGPT 桌面应用；从终端使用 Claude Code 或 Codex CLI 时则为终端应用）。更改后需退出并重新打开应用。首次联系人查找或发送时，macOS 可能另行请求通讯录访问或控制「信息」的权限，需允许。 验证连接：让客户端先调用 tool_check_db_access，再调用 tool_check_addressbook；两者成功后即可尝试读取或搜索。首次 uvx 启动可能因下载缓存 Python 依赖而较慢。 区域设置：服务器默认读取 Mac 自身区域设置；当号码所属区域与 Mac 配置不同时，设置 MAC_MESSAGES_REGION（ISO 3166-1 alpha-2 代码），区域在启动时解析一次，修改后需重启服务器。解析顺序为 MAC_MESSAGES_REGION、macOS AppleLocale 偏好、LC_ALL / LC_CTYPE / LANG，最后为 US。 另有 mac-messages-cli 命令行工具，可在终端读取、搜索和发送消息，使用相同的本地数据库与 macOS 权限；mac-messages-cli send 发送前要求 y/N 确认，当 stdin 非终端时除非传入 --yes 否则拒绝发送，查找失败时命令以非零退出码结束。 包也导出核心读/发函数供独立使用，这些调用使用相同的 macOS 权限且可能发送真实消息。
适用场景
- 用本地 MCP 客户端检索、整理和分析 iMessage 对话。
- 需要按联系人、群聊或附件元数据定位消息。
- 在明确调用发送工具时向个人或群聊发送文本与文件附件，或安排定时发送（依赖服务器进程保持存活）。
- 在终端环境中以 CLI 方式读写消息。
限制
- 仅支持 macOS。读取需要完全磁盘访问权限，发送需要 Mac 已登录「信息」且启动应用具有自动化「信息」的权限。
- 不支持的操作为：发送 Tapback、消息效果或主题行（只能发送文本与文件附件）；创建群聊、增删参与者、向群聊附加文件；编辑、撤回、删除或标记消息已读，以及保存草稿；编辑或合并已有联系人卡片。
- 定时发送不持久化，若客户端先断开连接，定时消息会丢失。
- 服务器本身不做人工确认，发送需由 MCP 客户端把关。
- 附带 Dockerfile 仅用于包与目录校验；Linux 容器无法访问 macOS TCC 权限或自动化 Messages.app，因此 Docker 不是读取或发送消息的受支持方式。
- 关于收费、价格、平台版本等信息暂未提供。
