マルチモーダル iMessage MCP

Claude向けの最も完全なiMessage MCPサーバー。Claude DesktopやClaude Codeから、会話の全文読み取り、メッセージ検索、画像添付ファイルの表示、メッセージ送信、連絡先検索、メッセージへのリアクションが可能です。

なぜこれが存在するのか

他のiMessage MCPツールは、Appleのchat.dbにあるtextカラムをクエリします。問題は？最新のmacOS（14+）では、93%のメッセージがtextではなくattributedBodyに保存されています。 それらのツールは黙って空または不完全な会話を返します。

このサーバーは、AppleのNSAttributedStringバイナリ形式をリバースエンジニアリングして実際のメッセージ内容を抽出し、完全なメッセージ履歴にアクセスできるようにします。

Related MCP server: jons-mcp-imessage

機能

マルチモーダル: Claudeが写真を見ることができる

get_attachmentを使用すると、画像はbase64コンテンツブロックとして返され、Claudeが実際に見ることができます。HEIC写真（iPhoneのデフォルト）は自動的にJPEGに変換されます。これにより、Claudeは以下が可能になります：

• 誰かが送った写真に何が写っているか説明する

• 画像からテキスト/スクリーンショットを読む

• 会話内の視覚コンテンツを分析する

要件

• macOS（これはローカルのiMessageデータベースを読み取ります）

• Node.js >= 18 および < 26。ロックされたネイティブSQLite依存関係がNode 26と互換性がないため、Node 24 LTSが推奨されます。

• ターミナルアプリにフルディスクアクセスが許可されていること（システム設定 > プライバシーとセキュリティ > フルディスクアクセス）。これは、連絡先名の解決に使用されるiMessageデータベースとAddressBookデータベースの両方をカバーします — Contactsアプリを実行している必要はありません。

インストール

git clone https://github.com/tszaks/imessage-mcp.git
cd imessage-mcp
npm install

設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.jsonに追加：

{
  "mcpServers": {
    "imessage": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/imessage-mcp/index.js"]
    }
  }
}

重要: nodeだけでなく、Node.jsバイナリのフルパス（例：/opt/homebrew/bin/node）を使用してください。macOSデスクトップアプリはシェルのPATHを継承せず、ベアのnodeコマンドはネイティブモジュールのクラッシュを引き起こす古いシステムNodeに解決されることがよくあります。

Claude Code

.mcp.jsonに追加：

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/path/to/imessage-mcp/index.js"]
    }
  }
}

Claude Codeでは、nodeはシェル環境を継承するため、通常は正しく解決されます。

使用例

"最近のメッセージを見せて" -- 最新の会話を読み取ります

"今日、ママから何がテキストで来た？" -- AddressBookを介して「ママ」を電話番号に解決し、会話を取得します

"「フライト確認」をメッセージで検索" -- すべてのメッセージの全文検索

"過去7日間に返信した、フォローアップが必要なアウトリーチ候補を見つけて" -- リスクラベル付きの構造化アウトリーチ候補を返します

"この10件のフォローアップテキストのバッチをプレビュー" -- 送信前に正確な受信者、メッセージ、警告、承認トークンを返します

"最近の配信失敗を表示" -- Messagesが失敗または保留中とマークした送信メッセージを報告し、後続のSMS/RCS送信がスレッドを復旧したかどうかも含みます

"メッセージ538516の写真を見せて" -- Claudeが表示して説明するための実際の画像を返します

"「10分遅れる」を+1234567890に送信" -- iMessageを送信します（確認が必要）

リリースフラグ

リリースフラグはMCPサーバー環境を介してオプトインします：

{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/path/to/imessage-mcp/index.js"],
      "env": {
        "IMESSAGE_MCP_RELEASES": "auto_sms_fallback,cleanup_failed_imessage_after_sms_fallback,message_mutation_tools,experimental_message_ui_actions,read_receipts"
      }
    }
  }
}

変異ツール

delete_messagesは正確なメッセージROWIDを受け入れます：

{ "message_ids": ["538516", "538517"] }

確認は必要ありません。削除されたID、見つからなかったID、バックアップ場所、検証中に見つかった残りの行を報告します。

delete_threadsは2段階の正確なバッチフローです：

{ "chat_ids": [101, 102] }

プレビューは、その順序付きリストとプレビューに表示されたスレッドメタデータに対して1つのapproval_tokenを返します。削除するには、同じ順序のchat_ids、confirm: true、およびそのトークンを送信します：

{ "chat_ids": [101, 102], "confirm": true, "approval_token": "..." }

順序、リスト、またはトークンを変更すると、リクエストは失敗します。

edit_messageとundo_send_messageは実験的です。Messagesがそれらのアクションに対して第一級のAppleScriptコマンドを公開していないためです。会話を開き、テキストスニペットで表示されている送信済み吹き出しを見つけ、コンテキストメニューを使用し、結果を検証します。これらは実際のMessagesの動作に影響を与えることを目的としており、偽のローカル専用DB編集ではありません。

オプションのチューニング：

IMESSAGE_MCP_SEND_VERIFY_DELAY_MS=2500

これは、MCPが新しい送信行についてローカルのMessagesデータベースをチェックする前に待機する時間を制御します。

仕組み

attributedBody修正

AppleのiMessageデータベース（~/Library/Messages/chat.db）には、メッセージコンテンツ用の2つのカラムがあります：

• text -- レガシーなプレーンテキストカラム（古いmacOSバージョンで使用）

• attributedBody -- シリアル化されたNSAttributedString blob（macOS 14+で使用）

最新のmacOSでは、Appleはリッチテキスト、メンション、フォーマットをサポートするために、メッセージストレージを徐々にattributedBodyに移行しました。textカラムはますます単なるレガシーフォールバックになりつつあり、しばしばNULLです。

このサーバーは、textがNULLのメッセージを検出し、バイナリNSTypedStream形式を解析してattributedBodyからコンテンツを抽出します：

1. バイナリblob内のNSStringマーカーを見つける

2. タイプヘッダーバイト（01 94 84 01 2b）を読み飛ばす

3. 長さプレフィックス（短いメッセージはシングルバイト、長いメッセージはマルチバイト）をデコードする

4. UTF-8テキストペイロードを抽出する

添付ファイル処理

iMessageの添付ファイルは~/Library/Messages/Attachments/に保存され、パスはattachmentテーブルで追跡されます。get_attachmentツール：

1. 指定されたメッセージIDの添付ファイルメタデータをクエリする

2. ~/Library/Messages/...パスを絶対パスに解決する

3. JPEG/PNG/GIF/WebPの場合：ファイルを読み取り、base64画像コンテンツを返す

4. HEIC（iPhoneのデフォルト）の場合：返す前にmacOSのsipsを使用してJPEGに変換する

5. その他のファイルの場合：メタデータとファイルパスを返す

トラブルシューティング

"Failed to open iMessage database" ターミナルアプリにフルディスクアクセスを許可する：システム設定 > プライバシーとセキュリティ > フルディスクアクセス。

連絡先検索で結果が返されない 連絡先解決は、macOSのAddressBook SQLiteデータベースを直接読み取ります（Contactsアプリは不要）。フルディスクアクセスが許可されていることを確認してください。連絡先が追加されたばかりの場合は、MCPサーバーを再起動してキャッシュを更新してください。

ネイティブモジュールのクラッシュ / "NODE_MODULE_VERSION mismatch" ネイティブ依存関係を再ビルドする：npm rebuild。これはNode.jsのバージョンが変更されたときに発生します。また、Claude Desktopの設定でnodeへのフルパスを使用していることを確認してください（上記の設定を参照）。

会話からのメッセージが欠落している これはまさにこのサーバーが修正するバグです。attributedBody抽出を含む最新バージョンを実行していることを確認してください。

ライセンス

MIT

クイックスタート要約

npm install
node index.js

次に、サーバーをMCPクライアントの設定に追加し、ターミナルアプリにフルディスクアクセスを許可します。

動作の仕組み（要約）

• macOSのiMessage SQLiteデータベースを読み取ります

• 最新のattributedBodyペイロードをデコードし、完全なメッセージテキストを取得します

• MCPを介して会話/検索/添付ファイルツールを公開します

• 明示的な確認を伴うメッセージ送信/リアクションアクションにAppleScriptを使用します

LLMクイックコピー

GitHubでこのコードブロックのコピーボタンを使用します。

Repo: imessage-mcp
Goal: Full iMessage MCP including attachments and send/reaction actions.
Setup:
1) npm install
2) Grant Full Disk Access to terminal app
3) Add MCP config entry for index.js
Use:
- read_recent_messages, search_messages, get_conversation
- list_chats_structured, get_conversation_by_chat_id, find_outreach_followups
- get_attachment for image/file analysis
- send_message/send_message_batch/react_to_message with explicit confirm flag
How it works:
- SQLite + attributedBody decoding + AppleScript actions wrapped as MCP tools