Apple Messages MCP

在 macOS 上，通过 Claude 读取和搜索你的 iMessage、SMS 和 RCS 对话。

配套项目 claude-connector-apple-mail 和 claude-connector-apple-reminders。

状态：读取和搜索已经稳定。发送功能可用，但尚未在真实发送中验证 — 脚本调用已实现且语法已验证，但 Apple 之前曾弄坏过 send，所以请把第一次真实发送当作测试。参见 发送消息。

工具

Related MCP server: jons-mcp-imessage

要求

• macOS 13 Ventura 或更高版本。RCS 需要 macOS 26 或更高版本。

• Claude 应用需要 Full Disk Access — 读取所必需。

• Messages 的 Automation 权限 — 发送和联系人姓名所必需。macOS 会自动提示授予此权限。

授予 Full Disk Access

1. System Settings → Privacy & Security → Full Disk Access

2. 启用 Claude（如果未列出，请使用 + 添加 /Applications/Claude.app）

3. 退出并重新打开 Claude。 macOS 会在进程启动时缓存此权限，因此必须重启 — 否则扩展会持续失败。

为什么这需要 Full Disk Access 而 Apple Mail 不需要

Apple Mail 扩展完全通过脚本与 Mail.app 通信，因此不需要特殊权限。Messages 无法这样工作。

Messages 的 AppleScript 字典恰好暴露了四个类 — account、chat、participant、file transfer — 并且没有 message 类。已在 macOS 26.5.2 上验证：

$ osascript -e 'tell application "Messages" to get every text message of first chat'
syntax error: Expected "from", etc. but found identifier. (-2741)

聊天和参与者可以正常枚举；消息正文则完全没有暴露。因此唯一的读取路径是通过 ~/Library/Messages/chat.db 的 SQLite，而该路径受 TCC 保护。与 Automation 不同，Full Disk Access 无法以编程方式请求 — 用户必须手动授予。

因此，该扩展对不同的任务使用这两种权限：

联系人姓名来自 Messages 的 participant 类（full name），它读取用户的 Contacts 名片。这绕开了单独受保护的 AddressBook 数据库 — 如果 Automation 被拒绝，handle 就只会显示为原始号码。

实现说明

attributedBody。 自 Ventura 起，message.text 经常为 NULL，正文位于 message.attributedBody 中，格式为 Apple typedstream — 即旧的 NSArchiver 格式，plistlib 无法读取。typedstream.py 用纯 Python 解码它，因此该扩展包不需要 PyObjC 依赖。它锚定 NSString/NSMutableString 类名，并在 + 类型标记之后读取带长度前缀的 UTF-8 负载。解码是彻底的：无法解码的正文会得到 None，而不会导致查询失败。

时间戳。 message.date 是 Apple 纪元（2001-01-01），在 macOS 13 之前为秒，之后为纳秒。两者都会被检测并处理。

搜索。 chat.db 没有附带文本索引，而且大多数正文只存在于 attributedBody 中，SQL 无法看到它们。这种组合比看起来更棘手。

最初的实现将谓词扩大为 m.text LIKE ? OR m.attributedBody IS NOT NULL，并在 Python 中重新过滤解码后的文本。由于第二个子句对几乎每一行现代数据都为真，查询的 LIMIT 在 Python 过滤器运行之前就把扫描截断为最新的几百条消息 — 因此任何更早的匹配都会悄然消失。搜索一条真实消息返回零结果，而不是变慢。在 916 MB 的历史记录上，这意味着搜索实际上只覆盖了最近几天。

解决办法是只解码一次，而不是每次查询都解码。index.py 将解码后并经过 casefold 处理的正文镜像到 ~/Library/Caches/apple-messages-mcp/search-index.db，搜索时再与该库进行 join — 因此匹配、过滤、排序和 LIMIT 都作用于 SQL 中的完整历史记录。该镜像具有以下特性：

• 增量式。 新消息通过 message.ROWID 水位线来发现。编辑和撤回会复用已有的 ROWID，因此每次刷新还会查看最近的 2000 行 — 但只查看那些设置了 date_edited 或两个正文列现在都为 NULL 的行，因为每次搜索都重新解码 2000 个 blob 是实实在在的工作，而且几乎总是毫无所获。如果 Messages 出于某种原因没有标记某次编辑，或者编辑早于该窗口，则需要 refresh_search_index(rebuild=True)。改进 attributedBody 解码器也需要重建；提升 SCHEMA_VERSION 会强制重建。

• 仅 casefold，仅此而已。 显示文本仍然来自 chat.db，因此该镜像纯粹是一个匹配判断器。存储 str.casefold() 可将其体积减半，并让不区分大小写的匹配对非 ASCII 字符也正确 — SQLite 的 LIKE 只对 ASCII 进行大小写折叠。

• 可丢弃。 它位于 ~/Library/Caches，如果被删除会重建。这里没有任何操作会写入 chat.db。

这里没有使用 FTS5，尽管早先的计划如此：FTS5 匹配整个词元，因此 MATCH 'dentist' 永远找不到 "mydentist"，这比 search_messages 所记录的子串语义更窄。对紧凑的 casefold 文本进行子串扫描已经很快，所以 FTS5 只会让索引体积翻倍，却提供我们无法使用的语义。如果将来某个查询确实变慢，再添加它也是一个可控的改动。

只读且不锁定。 连接以 mode=ro 打开，没有任何语句会修改数据库。如果 SQLite 无法以只读方式打开正在使用的 WAL，它会回退到私有快照副本，这样正在运行的 Messages.app 永远不会被打扰。

Tapbacks、编辑、回复。 反应从 associated_message_type 解码（2000–2007，3000 范围表示移除），线程回复从 thread_originator_guid 解码，编辑从 date_edited 解码。

发送消息

Messages 没有草稿对象，因此不存在与 Mail 扩展“草稿优先”设计完全对应的方案。所以写入路径分为两个层级，而且它们有意地并不等价。

compose_message — 安全的默认选项。 通过 imessage: / sms: URL scheme 打开 Messages，并预填收件人和正文，然后停下。由人来阅读并按下发送，因此不会有任何内容仅凭 Claude 的指示就离开机器。这也是启动新对话的唯一方式。完全不需要任何权限。

send_message — 立即送达。 使用脚本接口的 send，且无法撤回。它接受 chat_id 而不是电话号码，这并非限制，而正是关键所在：字典接受 participant 或 chat，而通过 GUID 指定现有聊天可以让 Messages 选择传输方式（iMessage / SMS / RCS），而不是由调用方猜测，从而避免在对方使用 iMessage 时悄悄发送 SMS。它还要求 confirm=True，纯粹是为了防止被随意触发。

哪些已得到验证，哪些没有

已在 macOS 26.5.2 上确认 — 字典暴露了

send : direct-parameter (file | text), to: (participant | chat)

service type 枚举为 SMS、iMessage、RCS，chat 具有可用于寻址的 GUID id 属性，并且生成的 AppleScript 可以编译。

未确认：真实发送是否真的能送达。 Apple 之前曾弄坏过 AppleScript send，而且它出现在字典中从来都不能证明它有效。测试套件中没有任何内容会实际发送消息，因此第一次真实发送就是实验。如果失败，使用“Send Message”操作的 shortcuts run 是接下来值得尝试的备选方案。

消息文本以 osascript 参数（on run argv）的形式到达 AppleScript，而不是被插值到脚本源码中，因此包含双引号的正文是惰性的，不会造成语法错误或注入。

发送附件尚未接通，不过 file 直接参数意味着它触手可及。

开发

python3 tests/test_db.py       # SQL, decoder, and search-index tests
python3 tests/test_send.py     # compose URLs, send guards, argv safety
python3 tools/probe_schema.py  # verify the real chat.db (needs Full Disk Access)
./build.sh                     # test, validate manifest, pack the .mcpb

tests/test_db.py 使用真实 schema 构建一次性数据库，因此无需 Full Disk Access 或真实消息历史即可验证 SQL。其中一个测试把匹配项埋在 3000 条较新消息之下，这正是针对上述截断搜索 bug 的回归测试。

tests/test_send.py 从不发送任何内容，也不会打开窗口：它覆盖 URL 构建器、保护子句以及确切的 osascript argv — 因此它在任何地方都是安全的，相应地也无法告诉你 Apple 的 send 是否有效。

两个测试套件都不会触碰真实的搜索索引；它们都会注入一个临时索引。

许可证

MIT