iMessage Max

iMessage Max

iMessage的高性能MCP（模型上下文协议）服务器，允许AI助手读取、搜索和发送具有适当联系人分辨率的消息。

内置Swift用于原生macOS集成-单个二进制文件，无运行时依赖关系。

分销状态

Swift二进制文件是当前版本支持的主要发行版：

• GitHub发布
• 自制水龙头
• 本地签名 make install 工作流

Python包作为遗留/次要路径保留在存储库中 不应假设与Swift实现具有相同的功能。

特性

• 12个意图对齐工具 -按照您自然提问的方式工作，而不是原始数据库查询
• 联系人解决方案 -通过macOS联系人查看姓名而不是电话号码
• 智能图像处理 -高效的图像变体（视觉/拇指/完整），以避免令牌膨胀
• 会话分组 -通过间隙检测将消息分组到对话会话中
• 附件跟踪 -知道哪些图像是本地可用的，哪些是卸载到iCloud的
• 本地性能 -Swift与原始SQLite3，核心图像GPU加速
• 只读安全 -仅从chat.db读取，发送需要明确的权限

为什么存在

大多数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")

安装

自制（推荐）

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

# Binary is at .build/release/imessage-max

稳定的开发安装工作流

对于本地开发，使用内置 make 工作流在 swift/ 而不是 手动重建和重新授予权限：

cd swift
make setup-signing   # one-time: create persistent signing identity
make install         # build, sign, restart launchd service, verify health

为什么这很重要：

• 它使用持久的本地标识对二进制文件进行签名，以便完整磁盘访问可以在重建过程中持续存在
• 它替换了原来的发布二进制文件
• 它重新启动所管理的launchd local.imessage-max 港口服务 8080
• 安装后验证服务是否正常

有用的命令：

cd swift
make status   # show process, signature, version, health
make restart  # restart the launchd service
make logs     # tail the stderr log
make clean    # remove debug artifacts and clear logs

设置

1.授予全磁盘访问权限

必须阅读 ~/Library/Messages/chat.db:

1. 打开 系统设置 → 隐私和安全 → 完全磁盘访问
2. 点击 + 添加二进制文件

对于Homebrew安装： 二进制文件位于 /opt/homebrew/Cellar/imessage-max/VERSION/bin/imessage-max （不是符号链接 /opt/homebrew/bin/).通过以下方式查找：

# Open the folder containing the actual binary
open $(dirname $(readlink -f $(which imessage-max)))

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

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

2.授予联系人访问权限

需要将电话号码解析为姓名。该应用程序将在首次运行时请求访问，或手动添加：

系统设置 → 隐私和安全 → 联系人 → add imessage-max

3.配置克劳德桌面

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

对于Homebrew：

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

对于源代码构建：

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

4.重新启动克劳德桌面

MCP现在应该出现在Claude的工具中。您可以通过以下方式进行验证 diagnose 工具。

已启动服务

如果您将iMessage Max作为后台HTTP服务运行 开发路径是launchd管理的二进制文件，位于：

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

该plist应指向：

/Users/YOU/.../imessage-max/swift/.build/release/imessage-max --http --port 8080

这 make install 工作流更新该二进制文件并重新启动 服务干净。

工具

find_chat

按参与者、姓名或最近的内容查找聊天记录。

find_chat(participants=["Nick"])           # Find DM with Nick
find_chat(participants=["Nick", "Andrew"]) # Find group with both
find_chat(name="Family")                   # Find by chat name
find_chat(contains_recent="dinner plans")  # Find by recent content

获取消息

使用灵活的筛选检索邮件。返回媒体的元数据。

get_messages(chat_id="chat123", limit=50)      # Recent messages
get_messages(chat_id="chat123", since="24h")   # Last 24 hours
get_messages(chat_id="chat123", from_person="Nick")  # From specific person

获取附件

通过具有分辨率变体的附件ID检索图像内容。

get_attachment(attachment_id="att123")                 # Default: vision (1568px)
get_attachment(attachment_id="att123", variant="thumb") # Quick preview (400px)
get_attachment(attachment_id="att123", variant="full")  # Original resolution

list_chats

浏览最近的聊天记录和预览。

list_chats(limit=20)          # Recent chats
list_chats(is_group=True)     # Only group chats
list_chats(since="7d")        # Active in last week

搜索

跨邮件进行全文搜索。

search(query="dinner")                    # Search all messages
search(query="meeting", from_person="Nick")  # From specific person
search(query="party", is_group=True)      # Only in group chats

get_text

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

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)

列表_附件

列出带有元数据的附件。包含 available 显示文件是否在磁盘上的字段。

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

获取_读取

获取未读邮件或摘要。

get_unread()                  # Unread from last 7 days
get_unread(since="24h")       # Last 24 hours
get_unread(mode="summary")    # Summary by chat

发送

发送邮件或文件附件（需要Messages.app的自动化权限）。

send(to="Nick", text="Hey!")
send(chat_id="chat123", text="Running late")
send(chat_id="chat123", file_paths=["/path/save-the-date.jpg"])
send(to="Nick", file_paths=["/path/invite.png"], text="Save the date")

规则：

• 正是其中之一 to 或 chat_id
• 至少一个 text 或 file_paths
• 如果两者都提供，则首先发送文件，最后发送文本
• reply_to 当前不受支持

发送结果语义：

• status: "sent" 表示消息或附件已成功确认
• status: "pending_confirmation" 表示邮件接受了附件发送，但未在轮询窗口内确认完成
• status: "failed" 表示发送失败
• status: "ambiguous" 意味着目标无法安全解决

笔记：

• pending_confirmation 是一种正常的非致命依恋状态，与硬失败不同
• 精确聊天向目标发送由标识的现有对话 chat_id

示例：

• {"status":"sent","success":true,...} 意味着在投票窗口内确认了交付
• {"status":"pending_confirmation","success":false,...} 表示消息已接受附件，但MCP尚无法确认最终完成

诊断

解决配置和权限问题。

diagnose()  # Returns: database status, contacts count, permissions, capabilities

HTTP模式

对于MCP路由器、MCP检查器或其他基于HTTP的集成：

imessage-max --http --port 8080

作为服务运行（推荐）

在以下位置创建launchd plist ~/Library/LaunchAgents/local.imessage-max.plist:

    Label
    local.imessage-max
    ProgramArguments
    
        /path/to/imessage-max
        --http
        --port
        8080
    
    RunAtLoad
    
    KeepAlive
    
    StandardOutPath
    /Users/YOU/Library/Logs/imessage-max.stdout.log
    StandardErrorPath
    /Users/YOU/Library/Logs/imessage-max.stderr.log

然后加载它：

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

MCP路由器集成

添加到MCP路由器作为远程流媒体服务器：

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路由器断开连接，它可以与新会话无缝重新连接
• 重新连接时没有“服务器已初始化”错误

故障排除

联系人显示为电话号码

跑 diagnose 检查状态。如果 contacts_authorized 为假：

• 添加 imessage-max 二进制到系统设置→ 隐私和安全→ 联系人

“找不到数据库”错误

添加 imessage-max 二进制到系统设置→ 隐私和安全→ 完全磁盘访问

图片显示“attachment_offloaded”错误

有些附件存储在iCloud中，而不是磁盘上。这 list_attachments 工具显示 available: true/false 对于每个附件。要下载卸载的附件，请在Messages.app中打开对话。

Claude Desktop中未加载MCP

1. 检查配置文件语法是否为有效的JSON
2. 验证二进制路径是否正确
3. 完全重新启动克劳德桌面（Cmd+Q）

建筑

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

需求

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

发展

cd swift
swift build           # Debug build
swift build -c release  # Release build
swift test            # Run tests

许可证

麻省理工学院