多模态 iMessage MCP

最完整的 iMessage MCP 服务器，专为 Claude 设计。在 Claude Desktop 或 Claude Code 中，即可读取完整对话、搜索消息、查看图片附件、发送消息、查找联系人以及对消息做出反应。

为何存在

其他 iMessage MCP 工具都查询 Apple 的 chat.db 中的 text 列。问题在于：在最新的 macOS（14+）上，93% 的消息存储在 attributedBody 中，而非 text。 那些工具会静默地返回空或不完整的对话。

本服务器逆向工程了 Apple 的 NSAttributedString 二进制格式，以提取实际的消息内容，让您能够访问完整的消息历史。

Related MCP server: jons-mcp-imessage

功能

多模态：Claude 可以查看您的照片

当您使用 get_attachment 时，图像会以 base64 内容块的形式返回，Claude 可以实际查看它们。HEIC 照片（iPhone 默认格式）会自动转换为 JPEG。这意味着 Claude 可以：

• 描述别人发给您的照片内容

• 读取图像中的文字/截图

• 分析对话中的视觉内容

要求

• macOS（此工具读取本地 iMessage 数据库）

• Node.js >= 18 且 < 26。推荐使用 Node 24 LTS，因为锁定的原生 SQLite 依赖与 Node 26 不兼容。

• 完全磁盘访问权限已授予您的终端应用（系统设置 > 隐私与安全性 > 完全磁盘访问权限）。这涵盖了 iMessage 数据库和用于联系人姓名解析的 AddressBook 数据库——无需运行通讯录应用。

安装

git clone https://github.com/tszaks/imessage-mcp.git
cd imessage-mcp
npm install

配置

Claude Desktop

添加到您的 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "imessage": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/imessage-mcp/index.js"]
    }
  }
}

重要： 请使用 Node.js 二进制文件的完整路径（例如 /opt/homebrew/bin/node），而不仅仅是 node。macOS 桌面应用不会继承您 shell 的 PATH，使用裸 node 命令通常会解析到较旧的系统 Node，导致原生模块崩溃。

Claude Code

添加到您的 .mcp.json：

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/path/to/imessage-mcp/index.js"]
    }
  }
}

在 Claude Code 中，node 通常能正确解析，因为它继承了您的 shell 环境。

使用示例

“显示我最近的消息” —— 读取您最新的对话

“妈妈今天给我发了什么短信？” —— 通过您的 AddressBook 将“妈妈”解析为电话号码，拉取对话

“搜索我的消息中的‘航班确认’” —— 在所有消息中进行全文搜索

“查找过去 7 天内回复过且需要跟进的外联对象” —— 返回带有风险标签的结构化外联候选

“预览这 10 条跟进短信的批次” —— 在发送前返回精确的收件人、消息、警告和批准令牌

“显示最近的发送失败” —— 报告 Messages 标记为失败或待发送的外发消息，包括后续 SMS/RCS 发送是否恢复了线程

“显示消息 538516 中的照片” —— 返回实际图像供 Claude 查看和描述

“向 +1234567890 发送‘晚到 10 分钟’” —— 发送 iMessage（需要确认）

发布标志

发布标志通过 MCP 服务器环境选择加入：

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/path/to/imessage-mcp/index.js"],
      "env": {
        "IMESSAGE_MCP_RELEASES": "auto_sms_fallback,cleanup_failed_imessage_after_sms_fallback,message_mutation_tools,experimental_message_ui_actions,read_receipts"
      }
    }
  }
}

修改工具

delete_messages 接受精确的消息 ROWID：

{ "message_ids": ["538516", "538517"] }

它不需要确认。它会报告已删除的 ID、缺失的 ID、备份位置以及在验证过程中发现的任何剩余行。

delete_threads 是一个两步精确批次流程：

{ "chat_ids": [101, 102] }

预览会为该有序列表和预览中显示的线程元数据返回一个 approval_token。要删除，请发送相同的排序 chat_ids、confirm: true 和该令牌：

{ "chat_ids": [101, 102], "confirm": true, "approval_token": "..." }

更改顺序、列表或令牌会导致请求失败。

edit_message 和 undo_send_message 是实验性的，因为 Messages 没有为这些操作暴露一流的 AppleScript 命令。它们会打开对话，通过文本片段找到可见的外发气泡，使用上下文菜单，然后验证结果。它们旨在影响实际的 Messages 行为，而不是伪造仅限本地的数据库编辑。

可选调优：

IMESSAGE_MCP_SEND_VERIFY_DELAY_MS=2500

这控制 MCP 在检查本地 Messages 数据库以获取新外发行之前等待的时间。

工作原理

attributedBody 修复

Apple 的 iMessage 数据库（~/Library/Messages/chat.db）有两个用于消息内容的列：

• text —— 传统的纯文本列（由较旧的 macOS 版本使用）

• attributedBody —— 序列化的 NSAttributedString 二进制大对象（由 macOS 14+ 使用）

在最新的 macOS 上，Apple 逐渐将消息存储迁移到 attributedBody，以支持富文本、提及和格式。text 列越来越只是一个通常为 NULL 的旧版回退。

本服务器检测到 text 为 NULL 的消息，并通过解析二进制 NSTypedStream 格式从 attributedBody 中提取内容：

1. 在二进制大对象中找到 NSString 标记

2. 读取类型头部字节（01 94 84 01 2b）之后的内容

3. 解码长度前缀（短消息为单字节，较长消息为多字节）

4. 提取 UTF-8 文本负载

附件处理

iMessage 附件存储在 ~/Library/Messages/Attachments/ 中，路径在 attachment 表中跟踪。get_attachment 工具：

1. 查询给定消息 ID 的附件元数据

2. 将 ~/Library/Messages/... 路径解析为绝对路径

3. 对于 JPEG/PNG/GIF/WebP：读取文件并返回 base64 图像内容

4. 对于 HEIC（iPhone 默认格式）：在返回前使用 macOS sips 转换为 JPEG

5. 对于其他文件：返回元数据和文件路径

故障排除

“无法打开 iMessage 数据库” 向您的终端应用授予完全磁盘访问权限：系统设置 > 隐私与安全性 > 完全磁盘访问权限。

联系人查找无结果 联系人解析直接读取 macOS AddressBook SQLite 数据库（无需通讯录应用）。确保已授予完全磁盘访问权限。如果刚刚添加了联系人，请重启 MCP 服务器以刷新缓存。

原生模块崩溃 / “NODE_MODULE_VERSION 不匹配” 重建原生依赖：npm rebuild。当您的 Node.js 版本更改时会发生这种情况。同时确保您的 Claude Desktop 配置使用 node 的完整路径（请参阅上面的配置）。

对话中缺少消息 这正是本服务器修复的错误。请确保您运行的是包含 attributedBody 提取功能的最新版本。

许可证

MIT

快速入门 TL;DR

npm install
node index.js

然后将服务器添加到您的MCP客户端配置中，并授予终端应用完整磁盘访问权限。

工作原理（TL;DR）

• 读取macOS iMessage SQLite数据库

• 解码现代 attributedBody 载荷以获取完整消息文本

• 通过MCP暴露对话/搜索/附件工具

• 使用AppleScript进行消息发送/反应操作，并带有明确确认

LLM快速复制

在GitHub上使用此代码块上的复制按钮。

Repo: imessage-mcp
Goal: Full iMessage MCP including attachments and send/reaction actions.
Setup:
1) npm install
2) Grant Full Disk Access to terminal app
3) Add MCP config entry for index.js
Use:
- read_recent_messages, search_messages, get_conversation
- list_chats_structured, get_conversation_by_chat_id, find_outreach_followups
- get_attachment for image/file analysis
- send_message/send_message_batch/react_to_message with explicit confirm flag
How it works:
- SQLite + attributedBody decoding + AppleScript actions wrapped as MCP tools