GoogleCalendarMCP

Fehrox/GoogleCalendarMCP

3.2

If you are the rightful owner of GoogleCalendarMCP and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Based.GCMCP is a Node/TypeScript MCP server that provides Google Calendar read/write access via MCP tools, with a local change log for tracking events.

Tools
7
Resources
0
Prompts
0

Based.GCMCP — Google Calendar MCP Server

Node/TypeScript MCP server that exposes Google Calendar read/write via MCP tools, with a local change log to track created/updated/deleted events.

Prereqs

  • Node 18+ (tested with Node 20/25)
  • npm
  • Google OAuth client (OAuth “Desktop app” recommended)

Install

cd /home/seb/Work/Based.GCMCP
npm install

Configure env

Create .env in the project root (see .env.example):

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REFRESH_TOKEN=...   # fill after bootstrap
GOOGLE_CALENDAR_IDS=       # optional comma-separated list, otherwise primary
DEFAULT_TIMEZONE=Australia/Brisbane
EVENTS_NEXT_DAYS=14
MAX_RESULTS_DEFAULT=50

Get a refresh token

npm run token:bootstrap
  1. Open the printed URL, approve access.
  2. The redirect to http://localhost:53682/oauth2callback will likely show a connection error; copy the code=... value from the URL bar.
  3. Paste the code back into the terminal.
  4. The script prints the refresh token (and writes to .env if it can). If .env already exists, paste GOOGLE_REFRESH_TOKEN=... manually.

Alternative: use Google OAuth Playground with your client ID/secret, Calendar scope, and copy the refresh token into .env.

Run the server

npm start

This builds (tsc) then runs the MCP server over stdio. MCP uses stdout for protocol messages, so .npmrc sets loglevel=silent to stop npm banners from polluting the stream; keep any logging on stderr.

Configure your MCP client to launch with:

  • command: npm
  • args: ["start"]
  • cwd: /home/seb/Work/Based.GCMCP

Add with codex mcp add

Register the server globally in Codex CLI:

codex mcp add /bin/bash -- -lc 'cd /home/seb/Work/Based.GCMCP && npm start' google-calendar-mcp

Adjust the cwd if you cloned elsewhere; the google-calendar-mcp name is arbitrary. Ensure your .env is populated before adding. If you prefer to avoid npm entirely, build once (npm run build) and point Codex at node /home/seb/Work/Based.GCMCP/dist/src/index.js.

Tools (stdio MCP)

  • health-status: check auth and list reachable calendars.
  • events-list: list events by time window; supports timeMin, timeMax, calendarIds?, query?, maxResults?, pageToken?, timeZone?.
  • events-next: upcoming events for the next N days (days?, default 14).
  • events-create: create event; dryRun defaults to true. Set dryRun:false to write.
  • events-update: update event (etag respected if provided); dryRun defaults to true.
  • events-delete: delete event (etag respected if provided); dryRun defaults to true.
  • events-changes: query the local change log.

Resources

  • calendar://list: calendar metadata list.
  • calendar://{calendarId}: metadata for a specific calendar.

Change tracking

Mutations append to data/event-log.json with operation, calendarId, eventId, etag, and timestamp. Query via events-changes (filter by operation/calendarId, limit).

Dry-run default

All mutating tools default to dryRun: true; set dryRun: false to actually write/update/delete.

Tests

npm test

Builds then runs node:test suites in dist/tests.

Notes

  • Timezone precedence: request param > calendar TZ > DEFAULT_TIMEZONE.
  • Pagination with multiple calendars is not supported (Google returns nextPageToken per calendar); use single calendar when paginating.
  • Retries/backoff are enabled for 429/5xx; per-request timeout is 10s.