imessage-mcp

imessage-mcp

通过 Claude、Codex、Cursor、VS Code 及任何其他 MCP 客户端搜索和阅读你的 Messages 历史记录。

只读。在你的 Mac 上运行。无需账户、云服务或编译。

• 按关键词、精确文本或短语搜索 iMessage、SMS、MMS 和 RCS 中的消息
• 阅读完整对话，包括编辑内容、撤回的消息、回应、回复和已读回执
• 查看他人发送给你的照片，并移除其中的位置数据
• 通过变更动态跟进新消息，并回答数量和响应时间相关的问题

安装

要求： macOS 14 或更高版本。使用 npx 安装需要 Node.js 24.16 或更高版本（Claude Desktop 自带运行环境）。如需支持加密缓存，请使用 Node 24 LTS。不具备 SQLite 检查点 API 的运行时（包括 Node 25）会在内存中搜索，并在重启后重建；doctor 会报告此情况。

适用于任何读取 mcpServers JSON 的客户端的标准配置：

{
  "mcpServers": {
    "imessage": {
      "command": "npx",
      "args": ["-y", "imessage-mcp@latest"]
    }
  }
}

接着，向运行它的应用授予完全磁盘访问权限：系统设置 > 隐私与安全性 > 完全磁盘访问权限，开启相应应用（Claude、你的终端、Cursor、VS Code 等），然后彻底退出并重新打开该应用。不确定该选哪个应用？在该应用的终端中运行 npx -y imessage-mcp@latest doctor，它会告诉你。在授予访问权限之前，每个工具都会显示相同的操作步骤。

amp mcp add imessage -- npx -y imessage-mcp@latest

claude mcp add --scope user imessage -- npx -y imessage-mcp@latest

codex mcp add imessage -- npx -y imessage-mcp@latest

[mcp_servers.imessage]
command = "npx"
args = ["-y", "imessage-mcp@latest"]

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "imessage": { "type": "local", "command": ["npx", "-y", "imessage-mcp@latest"], "enabled": true }
  }
}

code --add-mcp '{"name":"imessage","command":"npx","args":["-y","imessage-mcp@latest"]}'

如果 GUI 应用提示找不到 npx，说明它无法访问你的 Node 安装：请将 which npx 返回的完整路径用作 command。

使用方法

用日常语言提问：“帮我梳理一下最近的短信”“查找关于晚餐预订的消息”“Sam 通常多久回复？”客户端的提示词菜单中还提供三个提示词：

支持附加资源的客户端可以使用 imessage://conversations 和 imessage://conversations/{chat_id}。

工具

所有工具均为只读，并标记为 readOnlyHint。结果使用普通 ID（message_id、chat_id、attachment_id），可在不同工具间传递。

Apple 可能会在多个对话中记录同一条消息。搜索结果会将该消息仅返回一次，并附上所有规范的 chat_ids 及其 conversations 标签。单个成员关系也包含 chat_id 和 conversation；对于共享结果，请将 chat_ids 中相关的 ID 传递给 get_conversation。只有 Apple 提供的明确查找依据才会合并聊天别名。共享消息不会合并无关对话。

全局和联系人的消息数量会在请求范围内对共享记录去重。对话时间线和序列指标则会保留每条记录的成员关系，因此各对话的数量相加可能超过全局数量。同步变更会包含 chat_ids，并在 message_membership_changed 中提供 previous_chat_ids；其 changed_at 为 null，因为 Apple 不会为这些关联记录时间戳。记录的成员关系描述的是观察到变更时的状态；可用的文本、发送者和回执字段则描述当前源状态。升级索引格式会重建一次缓存，并使旧的同步游标失效；如果返回 DATABASE_CHANGED，请开始新的同步。

联系人姓名会扩展为所选人员的地址。即使通讯录中存在相互冲突的标签，精确电话号码或电子邮件也只会限定到该地址。resolve_contact 仍会报告身份歧义；限定地址不会合并人员，也不会包含其其他地址。对于类似地址的群组标题，请使用 conversation_names 范围进行搜索，并使用所选的 chat_id。

每个工具的输出架构都同时接受成功封装和结构化错误封装，因此严格模式的客户端可以展示原始原因和恢复提示。

默认情况下，对话读取采用严格模式。如果无法完整恢复正文或关联，错误会说明可使用 allow_partial: true 重试。部分结果会保留 completeness、警告以及每个事件的 row_status；引用证据前请先检查这些信息。缩小日期范围或使用 around_message_id 可以避开无关的受损事件。结构性故障仍会以失败关闭。

配置

向 args 添加选项，例如 ["-y", "imessage-mcp@latest", "--privacy", "redacted"]。

隐私与安全

• 只读。 服务以只读方式打开“信息”数据库，不提供发送、编辑、回应或标记已读的工具。
• 本地运行。 不使用账户，不收集遥测数据或分析数据。唯一的网络请求是可选的 npm 注册表版本检查。
• 客户端看到的是你请求的内容。 结果会发送到你使用的 MCP 客户端及其模型提供商，并受其政策约束。--privacy redacted 或 aggregate 会限制离开服务的数据。
• 搜索索引。 索引在你的 Mac 上构建；SQLite 检查点 API 可用时，会加密缓存到 ~/Library/Caches/imessage-mcp，密钥由“信息”数据库派生，因此只有已经能够读取你消息的应用才能打开它。删除缓存始终是安全的。即使缓存不可用或发生故障，server_status 也会报告相应情况，而搜索仍会从内存中继续进行。
• 不可信内容。 消息中可能包含用于操纵 AI 的文本。服务会告知客户端，必须将所有消息内容视为数据，绝不能视为指令。

详情请参阅：SECURITY.md 和 PRIVACY.md。

开发

npm ci
npm test      # unit tests on synthetic Messages databases
npm run e2e   # launches the built server over stdio and HTTP
npm run perf  # one-million-message performance gates

测试仅使用合成数据。请参阅 CONTRIBUTING.md。

依赖项 PR 通过作用域限定为仓库的 GitHub App 使用受保护的自动合并，无需续期个人访问令牌。每日运行的健康检查会检测身份验证失败和更新停滞；请参阅维护与恢复。

• 在确认 App 迁移完成且不再需要回滚后，弃用未使用的所有者令牌副本。
• 长时间不活跃后，确认 GitHub 未禁用定时工作流。依赖项合并不会发布版本。

许可证

MIT