Imessage Max

🚀 iMessage Max

iMessage Max是一款高性能的MCP（模型上下文协议）服务器，专为iMessage打造。它能使AI助手读取、搜索并发送消息，还可准确解析联系人信息。该项目采用Swift编写，能与macOS系统原生集成，仅为单一二进制文件，无需运行时依赖。

🚀 快速开始

安装

Homebrew（推荐）

brew tap cyberpapiii/tap
brew install imessage-max

从源码安装

git clone https://github.com/cyberpapiii/imessage-max.git
cd imessage-max/swift
swift build -c release

# 二进制文件位于 .build/release/imessage-max

配置

1. 授予全盘访问权限

要读取 ~/Library/Messages/chat.db，需要进行如下操作：

1. 打开 系统设置 → 隐私与安全性 → 全盘访问权限。
2. 点击 + 以添加二进制文件。

对于通过Homebrew安装的情况：二进制文件位于 /opt/homebrew/Cellar/imessage-max/VERSION/bin/imessage-max（而非 /opt/homebrew/bin/ 中的符号链接）。可使用以下命令找到它：

# 打开包含实际二进制文件的文件夹
open $(dirname $(readlink -f $(which imessage-max)))

对于从源码构建的情况：从克隆目录中添加 .build/release/imessage-max。

提示：在文件选择器中，按 ⌘+Shift+G 并粘贴路径，可直接导航。

2. 授予联系人访问权限

为了将电话号码解析为姓名，需要此权限。应用程序在首次运行时会请求该权限，也可以手动添加：

系统设置 → 隐私与安全性 → 联系人 → 添加 imessage-max。

3. 配置Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

对于Homebrew安装：

{
  "mcpServers": {
    "imessage": {
      "command": "/opt/homebrew/Cellar/imessage-max/1.0.0/bin/imessage-max"
    }
  }
}

对于从源码构建：

{
  "mcpServers": {
    "imessage": {
      "command": "/path/to/imessage-max/swift/.build/release/imessage-max"
    }
  }
}

4. 重启Claude Desktop

MCP现在应该会出现在Claude的工具中。你可以使用 diagnose 工具进行验证。

HTTP模式

若要用于MCP Router、MCP Inspector或其他基于HTTP的集成：

imessage-max --http --port 8080

作为服务运行（推荐）

在 ~/Library/LaunchAgents/local.imessage-max.plist 创建一个launchd plist文件：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>local.imessage-max</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/imessage-max</string>
        <string>--http</string>
        <string>--port</string>
        <string>8080</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/YOU/Library/Logs/imessage-max.stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/YOU/Library/Logs/imessage-max.stderr.log</string>
</dict>
</plist>

然后加载它：

launchctl load ~/Library/LaunchAgents/local.imessage-max.plist

MCP Router集成

将其作为远程可流式传输服务器添加到MCP Router：

INSERT INTO servers (id, name, server_type, remote_url, auto_start, disabled, created_at, updated_at)
VALUES ('imessage', 'imessage', 'remote-streamable', 'http://127.0.0.1:8080', 1, 0, strftime('%s','now'), strftime('%s','now'));

会话管理

HTTP传输支持干净的重新连接：

• 每个客户端连接都有自己独立的会话。
• 会话在1小时无活动后自动过期。
• 如果MCP Router断开连接，它可以使用新会话无缝重新连接。
• 重新连接时不会出现“服务器已初始化”错误。

✨ 主要特性

• 12种意图对齐工具：支持以自然提问的方式操作，而非使用原始数据库查询。
• 联系人解析：通过macOS联系人应用，显示联系人姓名而非电话号码。
• 智能图像处理：采用高效的图像变体（视觉/缩略图/全尺寸），避免令牌膨胀。
• 会话分组：将消息按对话会话分组，并检测对话间隙。
• 附件跟踪：可了解哪些图像本地可用，哪些已上传到iCloud。
• 原生性能：使用Swift和原生SQLite3，支持Core Image GPU加速。
• 只读安全：仅从chat.db读取数据，发送消息需要明确授权。

💻 使用示例

基础用法

find_chat

按参与者、名称或近期内容查找聊天记录。

find_chat(participants=["Nick"])           # 查找与Nick的私聊
find_chat(participants=["Nick", "Andrew"]) # 查找包含Nick和Andrew的群聊
find_chat(name="Family")                   # 按聊天名称查找
find_chat(contains_recent="dinner plans")  # 按近期内容查找

get_messages

灵活筛选并检索消息，返回媒体的元数据。

get_messages(chat_id="chat123", limit=50)      # 近期消息
get_messages(chat_id="chat123", since="24h")   # 过去24小时的消息
get_messages(chat_id="chat123", from_person="Nick")  # 来自特定人员的消息

get_attachment

根据附件ID检索图像内容，并提供不同分辨率的变体。

get_attachment(attachment_id="att123")                 # 默认：视觉分辨率 (1568px)
get_attachment(attachment_id="att123", variant="thumb") # 快速预览 (400px)
get_attachment(attachment_id="att123", variant="full")  # 原始分辨率

list_chats

浏览近期聊天记录并查看预览。

list_chats(limit=20)          # 近期聊天记录
list_chats(is_group=True)     # 仅显示群聊
list_chats(since="7d")        # 过去一周内活跃的聊天记录

search

对消息进行全文搜索。

search(query="dinner")                    # 搜索所有消息
search(query="meeting", from_person="Nick")  # 搜索来自特定人员的消息
search(query="party", is_group=True)      # 仅在群聊中搜索

get_context

获取特定消息周围的消息。

get_context(message_id="msg_123", before=5, after=10)

get_active_conversations

查找近期有来回互动的聊天记录。

get_active_conversations(hours=24)
get_active_conversations(is_group=True, min_exchanges=3)

list_attachments

列出附件及其元数据，包含 available 字段，显示文件是否在本地磁盘上。

list_attachments(type="image", since="7d")
list_attachments(chat_id="chat123", type="any")

get_unread

获取未读消息或摘要。

get_unread()                  # 过去7天内的未读消息
get_unread(since="24h")       # 过去24小时内的未读消息
get_unread(mode="summary")    # 按聊天记录汇总未读消息

send

发送消息（需要Messages.app的自动化权限）。

send(to="Nick", text="Hey!")
send(chat_id="chat123", text="Running late")

diagnose

排查配置和权限问题。

diagnose()  # 返回：数据库状态、联系人数量、权限信息

高级用法

图像变体说明

🔧 技术细节

架构

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude/AI      │◄───►│  iMessage Max   │◄───►│  chat.db        │
│  Assistant      │     │  (Swift MCP)    │     │  (SQLite)       │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                │
                                ▼
                        ┌─────────────────┐
                        │  Contacts.app   │
                        │  (CNContactStore)│
                        └─────────────────┘

开发

cd swift
swift build           # 调试构建
swift build -c release  # 发布构建
swift test            # 运行测试

要求

• macOS 13+（Ventura或更高版本）
• 全盘访问权限
• 联系人权限（用于名称解析）
• Messages.app的自动化权限（仅用于发送消息）

📄 许可证

本项目采用MIT许可证。

📚 详细文档

为何开发此项目

大多数iMessage工具会暴露原始数据库结构，每个用户意图通常需要调用3 - 5个工具。而这个MCP提供了与意图对齐的工具，示例如下：

"What did Nick and I talk about yesterday?"
→ find_chat(participants=["Nick"]) + get_messages(since="yesterday")

"Show me photos from the group chat"
→ list_attachments(chat_id="chat123", type="image")

"Find where we discussed the trip"
→ search(query="trip")

故障排除

联系人显示为电话号码

运行 diagnose 检查状态。如果 contacts_authorized 为false：

• 将 imessage-max 二进制文件添加到 系统设置 → 隐私与安全性 → 联系人。

“未找到数据库”错误

将 imessage-max 二进制文件添加到 系统设置 → 隐私与安全性 → 全盘访问权限。

图像显示 “attachment_offloaded” 错误

部分附件存储在iCloud中，而非本地磁盘。list_attachments 工具会为每个附件显示 available: true/false。要下载已卸载的附件，请在Messages.app中打开对话。

MCP未在Claude Desktop中加载

1. 检查配置文件语法是否为有效的JSON。
2. 验证二进制文件路径是否正确。
3. 完全重启Claude Desktop（Cmd+Q）。