微信扫一扫README
🚀 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，需要进行如下操作：
- 打开 系统设置 → 隐私与安全性 → 全盘访问权限。
- 点击 + 以添加二进制文件。
对于通过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() # 返回：数据库状态、联系人数量、权限信息
高级用法
图像变体说明
| 变体 | 分辨率 | 使用场景 | 令牌成本 |
|---------|------------|----------|------------|
| vision（默认） | 1568px | AI分析、OCR | ~1,600 令牌 |
| thumb | 400px | 快速预览 | ~200 令牌 |
| full | 原始分辨率 | 最大细节 | 不定 |
🔧 技术细节
架构
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 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中加载
- 检查配置文件语法是否为有效的JSON。
- 验证二进制文件路径是否正确。
- 完全重启Claude Desktop（Cmd+Q）。