imessage-mcp

imessage-mcp

Claude、Codex、Cursor、VS Code、その他あらゆるMCPクライアントから、Messagesの履歴を検索して読むことができます。

読み取り専用です。Mac上で動作します。アカウントもクラウドサービスも、コンパイルも不要です。

• iMessage、SMS、MMS、RCSのメッセージを、単語、完全一致テキスト、フレーズで検索できます
• 編集済みメッセージ、送信取り消しされたメッセージ、リアクション、返信、開封確認を含む会話全体を読み取れます
• 送られてきた写真を、位置情報を削除した状態で表示します
• 変更フィードで新着メッセージを追跡し、件数や返信時間に関する質問にも答えます

インストール

要件： macOS 14以降。npxでインストールする場合はNode.js 24.16以降（Claude Desktopには同梱されています）。暗号化キャッシュをサポートするにはNode 24 LTSを使用してください。Node 25など、SQLiteのチェックポイントAPIを備えていないランタイムでは、メモリ内で検索し、再起動後に再構築します。このことはdoctorで確認できます。

mcpServers JSONを読み込むすべてのクライアントで使える標準設定：

{
  "mcpServers": {
    "imessage": {
      "command": "npx",
      "args": ["-y", "imessage-mcp@latest"]
    }
  }
}

続いて、実行するアプリにフルディスクアクセスを許可します：「システム設定」>「プライバシーとセキュリティ」>「フルディスクアクセス」で、アプリ（Claude、ターミナル、Cursor、VS Codeなど）をオンにし、アプリを完全に終了してから再度開いてください。どのアプリか分からない場合は、そのアプリのターミナルからnpx -y imessage-mcp@latest doctorを実行してください。対象のアプリが表示されます。アクセスが許可されるまでは、どのツールも同じ手順を案内します。

amp mcp add imessage -- npx -y imessage-mcp@latest

claude mcp add --scope user imessage -- npx -y imessage-mcp@latest

codex mcp add imessage -- npx -y imessage-mcp@latest

[mcp_servers.imessage]
command = "npx"
args = ["-y", "imessage-mcp@latest"]

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "imessage": { "type": "local", "command": ["npx", "-y", "imessage-mcp@latest"], "enabled": true }
  }
}

code --add-mcp '{"name":"imessage","command":"npx","args":["-y","imessage-mcp@latest"]}'

GUI アプリで npx が見つからないと表示される場合、そのアプリから Node のインストールを参照できていません。which npx で確認したフルパスを command として使用してください。

使い方

「テキストメッセージの状況を教えて」「夕食の予約についてのメッセージを探して」「Sam の返信は通常どのくらい早い？」のように、自然な言葉で尋ねます。クライアントのプロンプトメニューには、次の 3 つのプロンプトもあります：

リソースをアタッチするクライアントでは、imessage://conversations と imessage://conversations/{chat_id} を使用できます。

ツール

すべてのツールは読み取り専用で、readOnlyHint が設定されています。結果ではプレーンなID（message_id、chat_id、attachment_id）を使用し、ツール間で受け渡せます。

Appleは同じメッセージを複数の会話に記録することがあります。検索ではそのメッセージを1回だけ返し、すべての正規の chat_ids と、それぞれに対応する conversations ラベルを含めます。参加先が1つだけの場合も chat_id と conversation が含まれます。共有された結果の場合は、chat_ids の該当するIDを get_conversation に渡してください。チャットのエイリアスが統合されるのは、Appleの明示的な照合情報がある場合に限られます。共有メッセージによって、無関係な会話が統合されることはありません。

全体および連絡先ごとのメッセージ数では、指定した範囲内の共有レコードが重複除外されます。会話のタイムラインとシーケンス指標では記録された各参加情報が保持されるため、会話ごとの件数を合計すると全体の件数を上回ることがあります。同期では変更内容に chat_ids が含まれ、previous_chat_ids を伴う message_membership_changed が出力されます。Appleはこれらの紐づけにタイムスタンプを付けないため、changed_at はnullです。記録された参加情報は変更が確認された時点の内容を示します。利用可能な本文、送信者、配信確認の各フィールドは、現在のソースの状態を示します。インデックス形式をアップグレードするとキャッシュが一度再構築され、古い同期カーソルは無効になります。DATABASE_CHANGED が返された場合は、新しい同期を開始してください。

連絡先名を指定すると、選択した人物のアドレスが検索対象に含まれます。連絡先に競合するラベルがある場合でも、電話番号またはメールアドレスを完全一致で指定すると、そのアドレスだけが対象になります。resolve_contact は引き続き、人物の特定に曖昧さがある場合に報告します。アドレスを対象に絞り込んでも、人物が統合されたり、他のアドレスが含まれたりすることはありません。グループ名がアドレス形式の場合は、conversation_names スコープで検索し、選択した chat_id を使用してください。

各ツールの出力スキーマは、成功時のエンベロープと構造化されたエラーエンベロープの両方を受け付けます。そのため、厳格なクライアントでも、元の理由と復旧のヒントを提示できます。

会話の読み込みはデフォルトで厳格に行われます。本文または関連情報を完全に復元できない場合、エラーに allow_partial: true を指定して再試行する方法が示されます。部分的な結果には completeness、警告、各イベントの row_status が含まれます。根拠を引用する前に、これらを確認してください。日付の範囲を狭めるか、around_message_id を指定すると、無関係な破損イベントを避けられる場合があります。構造上の障害がある場合は、引き続き処理を失敗させます。

設定

args にオプションを追加します。例：["-y", "imessage-mcp@latest", "--privacy", "redacted"]。

プライバシーとセキュリティ

• 読み取り専用です。 サーバーはメッセージデータベースを読み取り専用で開き、送信、編集、リアクション、既読にするためのツールはありません。
• ローカルで動作します。 アカウント、テレメトリー、分析はありません。ネットワークリクエストは、任意の npm レジストリへのバージョンチェックのみです。
• クライアントに表示されるのは、要求した内容です。 結果は、利用する MCP クライアントとそのモデルプロバイダーに、それぞれのポリシーに従って渡されます。--privacy redacted または aggregate を指定すると、サーバー外に出る情報が制限されます。
• 検索インデックス。 Mac 上で構築され、SQLite のチェックポイント API が利用可能な場合は、~/Library/Caches/imessage-mcp に暗号化してキャッシュされます。キーはメッセージデータベースを基に生成されるため、メッセージをすでに読み取れるアプリでのみ開けます。削除しても問題ありません。キャッシュが利用できないか失敗した場合、server_status がその状態を報告しますが、検索はメモリから続行されます。
• 信頼できないコンテンツ。 メッセージには、AI を操作するために書かれたテキストが含まれている場合があります。サーバーは、すべてのメッセージ内容を指示ではなくデータとして扱うよう、クライアントに伝えます。

詳細：SECURITY.md と PRIVACY.md。

開発

npm ci
npm test      # unit tests on synthetic Messages databases
npm run e2e   # launches the built server over stdio and HTTP
npm run perf  # one-million-message performance gates

テストには合成データのみを使用します。CONTRIBUTING.md を参照してください。

依存関係に関する PR は、個人用トークンを更新することなく、リポジトリに限定された GitHub App を通じて保護された自動マージを行います。毎日のヘルスチェックで、認証エラーや更新の停滞を検出します。メンテナンスと復旧を参照してください。

• App への移行を確認し、ロールバックが不要になった後で、未使用のオーナートークンのコピーを削除します。
• 長期間利用がなかった場合は、GitHub がスケジュールされたワークフローを無効にしていないことを確認します。依存関係のマージによってリリースが公開されることはありません。

ライセンス

MIT