Notesbridge

📝 NotesBridge

Use your Apple Notes from ChatGPT — search, read, and write, powered by your own Mac.

NotesBridge is a Model Context Protocol (MCP) connector that lets ChatGPT work with your Apple Notes. Every Notes action runs on your own Mac through a local agent. Requested note content travels through the hosted relay to ChatGPT; job arguments and results are temporarily stored in the relay database.

  ChatGPT  ──OAuth──►  NotesBridge relay  ──job queue──►  apple-notes-agent  ──►  Apple Notes.app

(connector) (Vercel, stateless) (your Mac, polls & executes) (on your Mac)

The agent accesses Apple Notes on your Mac. The relay stores account records and temporary job payloads/results; ChatGPT receives requested note content. Password-protected notes and attachment content are outside the verified read scope.

---

For users — 3 steps

1. Create your account at [notesbridge.vercel.app](https://notesbridge.vercel.app) and generate a pairing code.

2. Install the Mac agent (needs 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

The first time it touches Notes, macOS asks "Terminal wants to control Notes" — click OK (one time).

3. Connect ChatGPT: Settings → Plugins → turn on Developer mode (Security & login) → Create a custom plugin → paste the MCP Server URL `https://notesbridge.vercel.app/mcp` → Authentication OAuth → sign in & Allow.

That's it. In a new chat: *"Search my Apple Notes for the Q3 planning note"* or *"Create a note titled Groceries with milk, eggs, coffee."*

Your Mac must be awake with the agent running. npx apple-notes-agent install makes it start automatically at login and restart if it ever crashes.

Managing the agent

npx apple-notes-agent status      # is it paired & reachable?

npx apple-notes-agent logs # recent activity npx apple-notes-agent uninstall # stop auto-start

From this source checkout, for a private local text index (Node.js 22.13+), run node agent/cli.mjs index-install. This builds the index in batches of 25 notes and checks for changes every 15 minutes. index-status reports coverage. Search checks the current Notes metadata before using cached text, and falls back to live Notes when the index is stale. Password-protected content and attachment contents are excluded. The SQLite index stays in an owner-only directory on the Mac, outside the repository. The indexing commands are available in source; npm publication is separate.

---

What ChatGPT can do

---

Self-hosting

You can run your own relay so nothing depends on the hosted instance.

Prereqs: a Vercel account and a Supabase project (free tiers are fine).

1. Storage — in your Supabase project's SQL editor, run supabase/schema.sql. It creates a tiny Redis-shaped KV + queue surface (nb_* functions) with RLS on.
2. Deploy the server/ directory to Vercel.
3. Set env vars (see server/.env.example):

• SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY — your project + service-role key
• JWT_SECRET — openssl rand -hex 32

1. Verify: curl https://YOUR-APP.vercel.app/api/health → redisConfigured, redisOk, jwtSecretSet all true.
2. Point the agent at it: npx apple-notes-agent pair --server https://YOUR-APP.vercel.app.

---

How it works

• Auth — OAuth 2.1 with PKCE and Dynamic Client Registration (RFC 7591). ChatGPT registers itself, the user signs in on the NotesBridge consent page, and ChatGPT gets a scoped MCP access token. JWTs are HMAC-signed; three kinds (session, agent, mcp) with distinct privileges. Optional email verification via Resend (RESEND_API_KEY); off unless configured, and enforcement is opt-in (REQUIRE_EMAIL_VERIFICATION).
• Relay — MCP tool call → job pushed to jobs: (TTL ≤ the caller's wait window, so an abandoned job can't run late) → the Mac agent (holding a hanging long-poll) is handed the job within ~200ms, executes it, pushes the result → the MCP handler returns it. The long-poll means jobs are delivered on arrival rather than on a fixed interval, so relay overhead is ~300ms instead of ~1s. The agent is considered "online" only while it's actively connected.
• Agent — a dependency-free Node CLI. Tools run via JXA (osascript -l JavaScript) against Notes.app; arguments are passed as JSON over argv (never shell-interpolated). A macOS LaunchAgent keeps it alive across logins and crashes.

Repository layout

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

Development

# 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

Security & privacy

• Notes are read/written only on your Mac. The relay never persists note content — job payloads live in Redis-shaped storage with a short TTL and are deleted on delivery.
• The agent token is stored at ~/.notesbridge-agent.json (mode 600).
• No secrets are committed; see .gitignore and the .env.example files.
• Write tools are marked destructive so ChatGPT asks before overwriting.

License

MIT © Isaiah Dupree

Complete read coverage

list_notes and search return next_cursor. Pass it back until null; an empty search page can still have a cursor. Listings use stable note-ID order. Search reports password-protected notes as skipped. Run node test/live-all-notes.mjs for a read-only local coverage test after granting Notes automation. Current verification status is in the report.