lane-mac-mcp

一个用于 macOS 的只读 iMessage MCP 服务器 + CLI。单个可审计文件，无发送能力。

Claude（通过 MCP）或您（通过 CLI）可以列出会话、读取聊天记录、搜索消息历史——仅此而已。构造上只读：v1 完全不包含发送代码。 所有数据访问都通过 Apple 自带的 /usr/bin/sqlite3 以 -json -readonly 模式对 ~/Library/Messages/chat.db 进行；联系人姓名来自对本地 AddressBook 数据库的只读查询。

设计约束

整个服务器就是 server.ts（约 600 行，含注释），因此可以端到端审计——被审计的文件就是运行中的文件，因为 Node ≥ 22.18 直接执行 TypeScript，原生剥离类型（无构建步骤，无编译产物）。依赖恰好有两个，通过 package-lock.json 固定：@modelcontextprotocol/sdk 和 zod。无网络导入，无开放端口——仅 stdio JSON-RPC，由 Claude Desktop 作为子进程启动；CLI 运行是一次性进程。没有守护进程：Claude Desktop 随应用启动和停止服务器（重启应用以重新加载代码）。

Related MCP server: imessage-rich-search

要求

macOS 且已设置好“信息”，Node.js ≥ 22.18，并且运行服务器的进程需要完全磁盘访问权限：CLI 使用需要终端（或您的终端应用），MCP 使用需要 Claude Desktop。在“系统设置 → 隐私与安全性 → 完全磁盘访问权限”中授予，然后重启应用。node server.ts doctor 会检查所有这些并告诉您缺少什么。

设置

git clone <this repo> && cd MacMCPServer
npm install          # installs the two pinned dependencies
node server.ts doctor

然后将服务器添加到 Claude Desktop 的 claude_desktop_config.json（设置 → 开发者 → 编辑配置）：

{
  "mcpServers": {
    "lane-mac": {
      "command": "node",
      "args": ["/Users/you/Desktop/MacMCPServer/server.ts"]
    }
  }
}

重启 Claude Desktop。会出现三个工具：list_chats、read_chat、search_messages。

CLI 用法

node server.ts chats                                   # recent chats, names resolved
node server.ts chats --search "mom" --limit 5
node server.ts chats --awaiting-reply-only             # threads where the last word wasn't yours
node server.ts read "Martha" --limit 100               # fuzzy name; ambiguous → candidates
node server.ts read 42 --start-date 2024-01-01 --end-date 2024-06-30 --include-reactions
node server.ts search "dinner" --from "martha"         # last 30 days by default
node server.ts search "dinner" --start-date 2015-01-01 --deep   # older history + rich-text decode
node server.ts doctor

输出为 JSON。search 使用 SQL LIKE 覆盖 message.text；--deep 额外解码文本仅存在于 attributedBody blob 中的消息（有界扫描，较慢）。除非使用 --include-reactions，否则各处均排除 Tapback 反应。

已处理的 Apple 怪癖

时间戳是自 2001-01-01 以来的纳秒（非常旧的行是秒）——两者都会转换。消息文本通常存在于 attributedBody typedstream blob 中，而不是 message.text；在 JS 中使用已知的 NSString 启发式方法解码。联系人姓名通过所有 AddressBook 来源中归一化的后 10 位电话号码或小写电子邮件进行匹配，当联系人不可读时优雅地降级为原始号码。

隐私与安全姿态

服务器只能读取。它使用 sqlite3 的 -readonly 标志打开数据库，不包含任何写入数据库或发送消息的代码路径，不进行网络连接，也不监听任何端口。用户输入被转义到 SQL 字符串字面量中（'' 加倍），数值经过验证。doctor 仅打印行数，绝不打印消息内容。环境变量覆盖（CHAT_DB_PATH、SQLITE_BIN、ADDRESSBOOK_DIR）存在，以便测试永不接触真实数据。

测试

npm test

黑盒测试生成一个合成的 chat.db 和 AddressBook 夹具（包括仅 attributedBody 的消息、一个 tapback 和一个未回复的传入线程），并将真实 CLI 和真实 MCP stdio 接口作为子进程驱动。开发永不接触真实数据。

路线图（后续，非 v1）

联系人增强打磨 → 通过 osascript 读取备忘录 → 发送功能由 SEND_ENABLED 环境变量加每次调用批准来控制。