Notesbridge MCP server

📝 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. It never uploads your notes to a third party — every action runs on your own Mac through a tiny local agent. The cloud piece is only a stateless relay that shuttles requests between ChatGPT and your Mac.

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

Your Mac is the only place your notes are ever read or written. The relay stores only short-lived job payloads and your account record; it never sees a note unless a job is in flight, and jobs expire in seconds.

For users — 3 steps

1. Create your account at 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

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):

• SUPABASEURL, SUPABASESERVICEROLEKEY — 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

Shortened. The full README is on GitHub.