notesbridge

NotesBridge は、ChatGPT が Apple Notes を操作できる Model Context Protocol（MCP）コネクターです。Notes の操作はすべて、ローカルエージェントを介してご自身の Mac 上で実行されます。要求されたノートの内容はホストされたリレーを経由して ChatGPT に送信されます。ジョブの引数と結果は、リレーのデータベースに一時的に保存されます。

  ChatGPT  ──OAuth──►  NotesBridge relay  ──job queue──►  apple-notes-agent  ──►  Apple Notes.app
 (connector)          (Vercel, stateless)   (your Mac, polls & executes)         (on your Mac)

エージェントは Mac 上の Apple Notes にアクセスします。リレーにはアカウント情報と一時的なジョブのペイロード／結果が保存され、要求されたノートの内容は ChatGPT が受け取ります。パスワードで保護されたノートと添付ファイルの内容は、検証済みの読み取り対象外です。

---

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

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

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

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

Notes に初めてアクセスすると、macOS に 「Terminal wants to control Notes」 と表示されます。OK をクリックしてください（初回のみ）。

3. ChatGPT に接続： 設定 → プラグイン → Developer mode（Security & login）をオン → カスタムプラグインを 作成 → MCP Server URL https://notesbridge.vercel.app/mcp を貼り付け → 認証で OAuth を選択 → サインインして 許可。

これで完了です。新しいチャットで「Apple Notes から Q3 の計画に関するノートを検索して」や「Groceries というタイトルで、牛乳、卵、コーヒーが書かれたノートを作成して」と依頼できます。

エージェントの実行中は、Mac をスリープさせないでください。npx apple-notes-agent install を実行すると、ログイン時に自動起動し、クラッシュした場合も再起動するようになります。

エージェントの管理

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

このソースチェックアウトから、プライベートなローカルテキストインデックス（Node.js 22.13+）を作成するには、 node agent/cli.mjs index-install を実行します。ノートを 25 件ずつバッチ処理してインデックスを作成し、15 分ごとに変更を確認します。インデックスのカバー範囲は index-status で確認できます。 検索時にはキャッシュされたテキストを使用する前に Notes の現在のメタデータを確認し、インデックスが古い場合は Notes から直接取得します。パスワードで保護された内容と添付ファイルの内容は対象外です。SQLite インデックスはリポジトリの外にある、Mac 上の所有者のみがアクセスできるディレクトリに保存されます。 インデックス作成コマンドはソース内で使用できます。npm での公開とは別です。

---

ChatGPT でできること

ツール	操作
search	キーワードでノートを検索
fetch / get_note	ノートの全内容を読み取る
list_folders	ノート数とともにフォルダーを一覧表示
list_notes	ノートを一覧表示（フォルダーで絞り込み可能）
create_note	新しいノートを作成
append_to_note	ノートにテキストを追記
update_note	ノートを書き換える（破壊的な操作のため、ChatGPT が事前に確認します）

---

セルフホスト

ホストされたインスタンスに依存せず、ご自身のリレーを実行できます。

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

1. ストレージ — Supabase プロジェクトの SQL エディターで supabase/schema.sql を実行します。RLS が有効な、Redis 形式の小規模な KV とキューの機能（nb_* 関数）が作成されます。
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-notes-agent pair <CODE> --server https://YOUR-APP.vercel.app。

---

仕組み

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

リポジトリの構成

server/    Vercel functions: OAuth + MCP endpoint + relay        (deploy this)
agent/     apple-notes-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 の Redis 形式ストレージに保存され、配信時に削除されます。
• エージェントトークンは ~/.notesbridge-agent.json（モード 600）に保存されます。
• シークレットはコミットされません。.gitignore と .env.example ファイルを参照してください。
• 書き込みツールには破壊的な操作としてマークが付けられているため、上書きする前に ChatGPT が確認を求めます。

ライセンス

MIT © Isaiah Dupree

読み取り範囲の完全性

list_notes と search は next_cursor を返します。null になるまでカーソルを渡し直してください。検索結果が空のページでも、カーソルがある場合があります。リストは安定したノート ID 順です。検索では、パスワードで保護されたメモはスキップされたものとして報告されます。Notes の自動化を許可した後、読み取り専用のローカル網羅性テストとして node test/live-all-notes.mjs を実行してください。現在の検証状況はレポートに記載されています。