messages-bridge

MessagesBridge は、ChatGPT がiMessage の会話と連絡先を利用できるようにする Model Context Protocol（MCP）コネクターです。読み取りは、小さなローカルエージェントを通じてご自身の Mac 上で実行されます。要求された結果はホスト型リレーを経由して渡され、ChatGPT に返されます。リレーはリクエスト／結果のペイロードをキューに一時保存しますが、メッセージ履歴の恒久的なコピーは保持しません。

  ChatGPT  ──OAuth──►  MessagesBridge relay  ──job queue──►  apple-messages-agent  ──►  Messages.app + Contacts
 (connector)          (Vercel, stateless)      (your Mac, polls & executes)        (on your Mac)

メッセージが読み取られたり、連絡先が書き込まれたりするのは、ご自身の Mac 上だけです。リレーが保存するのは、有効期間の短いジョブのペイロードとアカウント情報のみです。ジョブの実行中を除き、リレーがメッセージを見ることはありません。また、キューのペイロードには短い有効期限が設定されています。

---

ユーザー向け — 3 ステップ

1. アカウントを作成します。 messagesbridge.vercel.app にアクセスし、ペアリングコードを生成します。

2. Mac エージェントをインストールします。（Node 18+ と Apple Command Line Tools が必要です。）

npx apple-messages-agent pair <YOUR-CODE>   # link this Mac to your account
npx apple-messages-agent install            # keep it running on every restart

エージェントには、macOS の権限を 2 つ付与する必要があります。メッセージ履歴を読み取るためのフルディスクアクセスを一度だけ許可します（システム設定 → プライバシーとセキュリティ → フルディスクアクセス）。また、メッセージの送信または連絡先の読み取りを初めて行う際にオートメーションを許可します。macOS に**「Terminal が Messages を制御しようとしています」という確認と、連絡先へのアクセス許可が表示されたら、「OK」**をクリックします。

3. ChatGPT に接続します。「設定」→ 「プラグイン」→ 「開発者モード」をオンにします（「セキュリティとログイン」）→ カスタムプラグインを「作成」→ MCP サーバーの URL **https://messagesbridge.vercel.app/mcpを貼り付けます → 認証で OAuth を選択 → サインインして「許可」**します。

これで完了です。新しいチャットで、*「夕食の予定についてのメッセージを検索して」や、「10 分遅れると Sarah にメッセージを送って」*と頼んでみてください。（送信前には毎回確認を求められます。）

エージェントの実行中は、Mac のスリープを解除しておく必要があります。npx apple-messages-agent install を実行すると、ログイン時に自動起動し、クラッシュした場合も再起動します。

エージェントの管理

npx apple-messages-agent status      # is it paired & reachable?
npx apple-messages-agent logs        # recent activity
npx apple-messages-agent uninstall   # stop auto-start

---

ChatGPT でできること

ツール	操作
search_messages	通常のテキストと Apple の属性付きテキストを検索します。結果ページが空でも next_cursor を使って続きを取得してください
list_recent_threads	最近の会話を新しい順に、最後のメッセージのプレビューとともに一覧表示します
get_thread	正確なチャット ID を使って会話をページ単位で読み取ります。next_cursor が null になるまで、cursor として渡してください
messages_status	メッセージの内容を返さずに、ローカルアクセス、件数、対象範囲を確認します
send_message	受信者 1 人に iMessage を送信します（事前に確認が必要です。一括送信はできません）
search_contacts	名前で連絡先を検索します（電話番号とメールアドレスを返します）
get_contact	名前または ID で連絡先を 1 件読み取ります
create_contact	連絡先を追加します（名前、任意の電話番号／メールアドレス）

読み取りが優先されます。書き込みツールは send_message と create_contact のみで、いずれも実行前に ChatGPT で確認を求められます。メッセージは常に一度に 1 人の受信者にのみ送信され、一括送信はできません。

---

セルフホスト

ホストされたインスタンスに依存しないよう、独自のリレーを実行できます。

前提条件： Vercel アカウントと Supabase プロジェクト（無料プランで問題ありません）。

1. ストレージ — Supabase プロジェクトの SQL エディターで、supabase/schema.sql を実行します。分離された actp_messagesbridge_* テーブルと、RLS およびサービスロールのみへの権限付与を備えた mb_* ストレージ関数が作成されます。
2. デプロイ — server/ ディレクトリを Vercel にデプロイします。
3. 環境変数を設定 — server/.env.example を参照してください。
   • SUPABASE_URL、SUPABASE_SERVICE_ROLE_KEY — プロジェクトとサービスロールキー
   • JWT_SECRET — openssl rand -hex 32
4. 検証： curl https://YOUR-APP.vercel.app/api/health → redisConfigured、redisOk、jwtSecretSet がすべて true。
5. エージェントの接続先を指定します：npx apple-messages-agent pair <CODE> --server https://YOUR-APP.vercel.app。

---

仕組み

• 認証 — PKCE と Dynamic Client Registration（RFC 7591）を使用する OAuth 2.1。ChatGPT が自身を登録し、ユーザーは MessagesBridge の同意ページでサインインすると、ChatGPT はスコープが限定された MCP アクセストークンを取得します。JWT は HMAC で署名され、権限の異なる 3 種類（session、agent、mcp）があります。Resend（RESEND_API_KEY）によるメール認証は任意です。設定されていない場合は無効で、認証の必須化も任意です（REQUIRE_EMAIL_VERIFICATION）。
• リレー — MCP ツール呼び出し → jobs:<user> にジョブを送信（TTL は呼び出し元の待機時間以下に設定し、放棄されたジョブが遅れて実行されないようにします）→ 長時間ポーリングを保持している Mac エージェントに約 200ms 以内にジョブを渡し、実行して結果を送信 → MCP ハンドラーが結果を返します。長時間ポーリングにより、ジョブは一定間隔ではなく到着時に配信されるため、リレーのオーバーヘッドは約 1 秒ではなく約 300ms です。エージェントは、実際に接続されている間のみ「オンライン」と見なされます。
• エージェント — 依存関係のない Node CLI です。読み取りツールは Messages の chat.db を直接クエリします（読み取り専用の SQLite）。送信ツールと連絡先ツールは、Messages.app および Contacts に対して JXA（osascript -l JavaScript）を実行します。引数は argv 経由で JSON として渡されます（シェルによる文字列補間は行いません）。macOS LaunchAgent により、ログイン後やクラッシュ後も実行状態が維持されます。

リポジトリの構成

server/    Vercel functions: OAuth + MCP endpoint + relay        (deploy this)
agent/     apple-messages-agent — the npm-published Mac CLI          (users npx this)
kit/       Browser automations: register the dev-mode connector AND
           fill the OpenAI directory submission (see kit/README.md)
supabase/  schema.sql for self-hosting the storage
test/      end-to-end OAuth + MCP integration test

開発

# server
cd server && cp .env.example .env.local   # fill in, then: vercel dev
# end-to-end test against a live deployment (reads ../.env.local)
node test/e2e-oauth.mjs
# agent unit tests
node --test agent/test-agent-unit.mjs

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

• メッセージの読み取りと送信、および連絡先の読み取りと追加は、お使いの Mac 上でのみ行われます。リレーは要求されたコンテンツをジョブ／結果キューに短時間だけ保存し、TTL も短く設定します。結果は配信時に消費されます。
• エージェントトークンは ~/.messagesbridge-agent.json に保存されます（モード 600）。
• シークレットはコミットされません。.gitignore と .env.example ファイルを参照してください。
• 書き込みツールは破壊的な操作としてマークされているため、ChatGPT はメッセージの送信や連絡先の追加前に確認を求めます。送信のたびに、確認済みの受信者 1 人にのみ送信され、一括送信は行われません。

ライセンス

MIT © Isaiah Dupree

検証済みの読み取り範囲とライブテスト

Agent 1.1 はライブの SQLite WAL を読み取り、macOS Foundation を使用して Apple の属性付き文字列をデコードし、上限付きのカーソルページネーションを提供します。カーソルはデータベースへの挿入順に従います。添付ファイルのみのレコードも has_attachments を通じて表示されますが、添付ファイルはアップロードもデコードもされません。Mac のデータベースがカバレッジの境界となります。これにより、すべての iPhone／iCloud メッセージが同期されていると確認できるわけではありません。

apple-messages-agent doctor
node test/live-messages.mjs
# After pairing your own account and starting the agent:
MB_EMAIL=your-email MB_PASSWORD=your-password node test/live-relay.mjs

認証情報は共有されるトランスクリプトやコミット済みファイルではなく、安全な環境から提供してください。ライブテストは集計結果の読み取りと出力のみを行います。live-messages は、すべてのローカル会話ページ、最大スレッド内のすべてのメッセージ、デコード済み検索、カーソル検証を確認します。live-relay は、実際の OAuth、MCP、ペアリング済み Mac の読み取りを検証し、Mac がオフラインの場合は失敗します。レビュアー／デモ向けの出力は、ライブ統合の証拠として認められません。

本番環境では、ストレージのマイグレーションと有効な Supabase 設定が必要です。ストレージが利用できない場合、/api/health は HTTP 503 を返します。以前のリレーデータベースが利用できない場合、そのデータベースに保存されているアカウント、ペアリング、OAuth セッションは自動的に復元できません。オーナーアカウントにサインインまたは作成し、プラグインを再接続してください。