Apple Messages MCP

macOS 上で Claude から iMessage、SMS、RCS の会話を読み取り・検索します。

関連プロジェクト: claude-connector-apple-mail および claude-connector-apple-reminders。

ステータス: 読み取りと検索は安定しています。送信は動作しますが、実際の送信については未検証です — スクリプト呼び出しは実装済みで構文も確認済みですが、Apple はこれまでに send を壊したことがあるため、最初の実際の送信はテストとして扱ってください。詳細は メッセージの送信 を参照してください。

ツール

Related MCP server: jons-mcp-imessage

必要条件

• macOS 13 Ventura 以降。RCS には macOS 26 以降が必要です。

• Claude アプリに対する フルディスクアクセス — 読み取りに必要です。

• Messages に対する 自動化 権限 — 送信と連絡先名に必要です。 macOS はこれを自動的にプロンプト表示します。

フルディスクアクセスを許可する方法

1. システム設定 → プライバシーとセキュリティ → フルディスクアクセス

2. Claude を有効にする (一覧にない場合は + で /Applications/Claude.app を追加)

3. Claude を終了して再度開きます。 macOS はこの権限をプロセス起動時にキャッシュするため、 再起動は必須です — これを行わないと拡張機能は動作し続けられません。

Apple Mail と異なり、なぜフルディスクアクセスが必要なのか

Apple Mail 拡張機能は Mail.app と完全にスクリプト経由でやり取りするため、 特別な権限は不要です。しかし Messages はそうはいきません。

Messages の AppleScript 辞書が公開しているのは正確に 4 つのクラス — account、 chat、participant、file transfer — であり、メッセージクラスはありません。 macOS 26.5.2 で確認済み:

$ osascript -e 'tell application "Messages" to get every text message of first chat'
syntax error: Expected "from", etc. but found identifier. (-2741)

チャットと参加者の列挙は問題なくできますが、メッセージの 本文 は単純に公開されていません。 したがって、唯一の読み取り経路は ~/Library/Messages/chat.db 上の SQLite であり、これは TCC で保護されています。Automation と異なり、Full Disk Access はプログラムから 要求できません — ユーザーが手動で許可する必要があります。

このため、拡張機能は 2 つの権限をそれぞれ異なる目的で使用します:

連絡先名は Messages の participant クラス (full name) から取得されます。これにより、 個別に保護されている AddressBook データベースを回避できます — Automation が拒否された場合、 ハンドルは単に生の数字として表示されます。

実装上の注意

attributedBody. Ventura 以降、message.text は頻繁に NULL になり、 本文は message.attributedBody に Apple の typedstream として格納されます — これは従来の NSArchiver 形式であり、plistlib では読み取れません。typedstream.py はこれを 純粋な Python でデコードするため、バンドルに PyObjC 依存は不要です。これは NSString/NSMutableString クラス名をアンカーとし、+ 型マーカーの後に続く 長さプレフィックス付き UTF-8 ペイロードを読み取ります。デコードは全か無かです: デコードできない本文は None を返し、クエリ自体は失敗しません。

タイムスタンプ. message.date は Apple エポック (2001-01-01) 基準で、macOS 13 より前は 秒、以降は ナノ秒 です。両方とも検出して処理します。

検索. chat.db にはテキストインデックスがなく、ほとんどの本文は attributedBody にのみ存在するため、SQL からは見えません。この組み合わせは 見た目以上に厄介です。

最初の実装では述語を m.text LIKE ? OR m.attributedBody IS NOT NULL に広げ、デコードした テキストを Python 側で再フィルタリングしていました。しかしこの 2 番目の句はほぼすべての最新 行に対して真となるため、クエリの LIMIT がスキャンを最新の数百メッセージに切り詰め、 Python フィルタが実行される前に — それより古い一致は静かに消えていました。実際の メッセージに対する検索は、遅いどころか結果ゼロを返していました。916 MB の 履歴では、検索が事実上最後の数日分しかカバーしないことを意味していました。

修正方法は、クエリごとにデコードするのではなく一度だけデコードすることです。index.py はデコード済み・ ケースフォールド済みの本文を ~/Library/Caches/apple-messages-mcp/search-index.db にミラーリングし、 検索はそれに対して JOIN します — これにより、一致、フィルタ、並び順、 LIMIT のすべてが SQL 内で完全な履歴に適用されます。ミラーは次のとおりです:

• 増分更新。 新しいメッセージは message.ROWID ウォーターマークで検出されます。 編集と送信取り消しは既存の ROWID を再利用するため、各リフレッシュでは最新の 2000 行も確認します — ただし、date_edited が設定されている行、または両方の 本文列が NULL になっている行のみを対象とします。なぜなら、2000 個の blob を検索のたびに 再デコードするのは実質的な作業であり、ほとんどの場合何も見つからないからです。 Messages が何らかの理由でスタンプを付けなかった編集、またはそのウィンドウより古い編集は、 refresh_search_index(rebuild=True) が必要です。attributedBody デコーダの改善も 再構築を正当化します; SCHEMA_VERSION を上げれば強制的に再構築されます。

• ケースフォールドのみ。 表示テキストは依然として chat.db から取得されるため、 ミラーは純粋にマッチングのためのものです。str.casefold() を格納することでサイズが半分になり、 非 ASCII に対しても大文字小文字を区別しないマッチングが正しく機能します — SQLite の LIKE は ASCII のみで大文字小文字を畳み込みます。

• 使い捨て。 これは ~/Library/Caches に置かれ、削除されれば再構築されます。 ここから chat.db に書き込むことは一切ありません。

FTS5 ではありません。以前の計画にもかかわらず: FTS5 はトークン単位でマッチするため、 MATCH 'dentist' は "mydentist" を見つけられません。これは search_messages が文書化している 部分文字列セマンティクスよりも狭いものです。コンパクトなケースフォールド済みテキストに対する 部分文字列スキャンはすでに高速なので、FTS5 は使用できないセマンティクスのために インデックスを 2 倍にするだけです。将来クエリが遅くなった場合に備えて、後から追加するのは 限定的な変更で済みます。

読み取り専用・非ロック。 接続は mode=ro で開かれ、ステートメントは データベースを変更しません。SQLite がライブの WAL を読み取り専用で開けない場合は、 プライベートなスナップショットコピーにフォールバックするため、実行中の Messages.app を 妨害することはありません。

Tapback、編集、返信。 リアクションは associated_message_type (2000–2007、および削除を示す 3000 番台) からデコードされ、 スレッド返信は thread_originator_guid から、編集は date_edited から取得されます。

メッセージの送信

Messages には下書きオブジェクトがないため、Mail 拡張機能の 下書き優先設計に正確に対応するものはありません。書き込み経路には 2 つのレベルがあり、 それぞれ意図的に異なっています。

compose_message — 安全なデフォルト。 受信者と 本文を imessage: / sms: URL スキームで事前入力した状態で Messages を開き、そこで停止します。 人間がそれを読んで送信ボタンを押すため、Claude の判断だけでマシンから情報が送信されることはありません。 これは 新しい 会話を開始する唯一の方法でもあります。権限はまったく必要ありません。

send_message — 即座に配信。 スクリプティングインターフェースの send を使用し、取り消しはできません。電話番号ではなく chat_id を受け取りますが、 これは制限ではなく意図的な設計です: 辞書は participant と chat のどちらも受け付け、 既存のチャットを GUID で指定することで、呼び出し側が推測して iMessage 利用者に SMS を静かに送信するのではなく、Messages 側がトランスポート (iMessage / SMS / RCS) を 選択できます。また、confirm=True が必須であり、これは単に不注意で 起動されるのを防ぐためのガードです。

検証済みのことと、未検証のこと

macOS 26.5.2 で確認済み — 辞書は以下を公開しています:

send : direct-parameter (file | text), to: (participant | chat)

service type 列挙は SMS、iMessage、RCS であり、chat には アドレス指定のための GUID id プロパティがあり、生成された AppleScript はコンパイルされます。

未確認: 実際の送信が本当に配信されるかどうか。 Apple は過去に AppleScript の send を壊したことがあり、辞書に存在することが 動作の証明になったことはありません。テストスイートはメッセージを配信しないため、 最初の実際の送信が実験となります。失敗した場合、shortcuts run と "Send Message" アクションを 使う方法が次に試す価値のあるフォールバックです。

メッセージテキストは AppleScript に osascript 引数 (on run argv) として渡され、 スクリプトソースに補間されるわけではないため、二重引用符を含む本文は 構文エラーやインジェクションではなく、単に無害です。

添付ファイルの送信は配線されていませんが、file 直接パラメータがあるため 実現可能な範囲にあります。

開発

python3 tests/test_db.py       # SQL, decoder, and search-index tests
python3 tests/test_send.py     # compose URLs, send guards, argv safety
python3 tools/probe_schema.py  # verify the real chat.db (needs Full Disk Access)
./build.sh                     # test, validate manifest, pack the .mcpb

tests/test_db.py は実際のスキーマで使い捨てデータベースを構築するため、 Full Disk Access や実際のメッセージ履歴がなくても SQL を検証できます。そのうちの 1 つは 3000 件の新しいメッセージの下に一致を埋め込んでおり、上記で説明した 切り詰め検索バグの回帰テストとなっています。

tests/test_send.py は何も送信せず、ウィンドウも開きません: URL ビルダー、 ガード句、正確な osascript argv をカバーしています — そのためどこでも安全に実行でき、 その代わりに Apple の send が動作するかどうかは教えてくれません。

どちらのスイートも実際の検索インデックスには触れず、両方とも一時的なものを注入します。

ライセンス

MIT