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()  # 返回：數據庫狀態、聯繫人數量、權限信息

高級用法

圖像變體說明

變體	分辨率	使用場景	令牌成本
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中加載

1. 檢查配置文件語法是否為有效的JSON。
2. 驗證二進制文件路徑是否正確。
3. 完全重啟Claude Desktop（Cmd+Q）。