Calendar Bridge README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Calendar Bridge listing page.
📅 CalendarBridge
Your Apple Calendar, in ChatGPT — on your own Mac.
CalendarBridge is a Model Context Protocol (MCP) connector that lets ChatGPT work with your Apple Calendar. It never uploads your events 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.
Your Mac is the only place your events are ever read or written. The relay stores only short-lived job payloads and your account record; it never sees an event unless a job is in flight, and jobs expire in seconds.
For users — 3 steps
1. Create your account at calendarbridge.vercel.app and generate a pairing code.
2. Install the Mac agent (needs Node 18+):
The first time it touches Calendar, macOS asks "Terminal wants to control Calendar" — 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://calendarbridge.vercel.app/mcp → Authentication OAuth → sign in & Allow.
That's it. In a new chat: "Search my Apple Calendar for the dentist appointment" or "Add a Team Standup to my Work calendar tomorrow at 9am."
Your Mac must be awake with the agent running.
npx calendar-agent installmakes it start automatically at login and restart if it ever crashes.
Managing the agent
What ChatGPT can do
| Tool | Action |
|---|---|
list_calendars | List all your calendars (Work, Personal, Family, …) |
list_events | List upcoming events in a date window (default next 7 days), optionally one calendar |
search_events | Find events whose title contains a keyword |
get_event | Read one event by id |
create_event | Create an event (title, start, end, optional location, notes, calendar, all-day) |
update_event | Edit an event's fields (overwrites the fields you pass — read it first) |
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).
- 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. - Deploy the
server/directory to Vercel. - Set env vars (see
server/.env.example):SUPABASE_URL,SUPABASE_SERVICE_ROLE_KEY— your project + service-role keyJWT_SECRET—openssl rand -hex 32
- Verify:
curl https://YOUR-APP.vercel.app/api/health→redisConfigured,redisOk,jwtSecretSetalltrue. - Point the agent at it:
npx calendar-agent pair <CODE> --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 CalendarBridge 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:<user>(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 Calendar.app; arguments are passed as JSON over argv (never shell-interpolated). A macOS LaunchAgent keeps it alive across logins and crashes.
Repository layout
Development
Security & privacy
- Events are read/written only on your Mac. The relay never persists event content — job payloads live in Redis-shaped storage with a short TTL and are deleted on delivery.
- The agent token is stored at
~/.calendarbridge-agent.json(mode600). - No secrets are committed; see
.gitignoreand the.env.examplefiles. - Write tools are marked destructive so ChatGPT asks before changing an event.
License
MIT © Isaiah Dupree