Imessage Max

🚀 iMessage Max

iMessage用の高性能MCP（Model Context Protocol）サーバーです。このサーバーを使うと、AIアシスタントがメッセージを読み、検索し、適切な連絡先解決を行って送信することができます。

macOSとのネイティブ統合のためにSwiftで構築されており、単一のバイナリで、ランタイム依存関係はありません。

✨ 主な機能

• 12の意図に沿ったツール - 自然な質問の方法で作業でき、生のデータベースクエリを使用する必要はありません。
• 連絡先解決 - macOSの連絡先を介して、電話番号ではなく名前を表示します。
• スマートな画像処理 - トークンの増加を避けるため、効率的な画像バリアント（vision/thumb/full）を使用します。
• セッショングルーピング - メッセージを会話セッションにグループ化し、ギャップを検出します。
• 添付ファイル追跡 - どの画像がローカルに利用可能で、どれがiCloudにオフロードされているかを把握します。
• ネイティブなパフォーマンス - 生のSQLite3とCore ImageのGPUアクセラレーションを備えたSwiftで構築されています。
• 読み取り専用安全 - 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")

📦 インストール

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ツールで確認できます。

💻 使用例

find_chat

参加者、名前、または最近の内容でチャットを検索します。

find_chat(participants=["Nick"])           # NickとのDMを検索
find_chat(participants=["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")                 # デフォルト: vision (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")        # 過去1週間にアクティブなチャット

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のAutomation許可が必要です）。

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

diagnose

設定と許可の問題をトラブルシューティングします。

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が切断された場合、新しいセッションでシームレスに再接続できます。
• 再接続時に「Server already initialized」エラーは発生しません。

トラブルシューティング

連絡先が電話番号で表示される

diagnoseを実行して状態を確認します。contacts_authorizedがfalseの場合：

• システム設定 → プライバシーとセキュリティ → 連絡先にimessage-maxバイナリを追加します。

"Database not found"エラー

システム設定 → プライバシーとセキュリティ → フルディスクアクセスにimessage-maxバイナリを追加します。

画像が"attachment_offloaded"エラーを表示する

一部の添付ファイルはiCloudに保存されており、ディスク上にはありません。list_attachmentsツールは各添付ファイルのavailable: true/falseを表示します。オフロードされた添付ファイルをダウンロードするには、Messages.appで会話を開きます。

MCPがClaude Desktopに読み込まれない

1. 設定ファイルの構文が有効なJSONであることを確認します。
2. バイナリのパスが正しいことを確認します。
3. Claude Desktopを完全に再起動します（Cmd+Q）。

🔧 技術詳細

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

要件

• macOS 13+（Ventura以降）
• フルディスクアクセス許可
• 連絡先許可（名前解決用）
• Messages.appのAutomation許可（送信のみ）

開発

cd swift
swift build           # デバッグビルド
swift build -c release  # リリースビルド
swift test            # テストを実行

📄 ライセンス

MIT