mcp-google-calendar: Instructions file for Claude Code

CLAUDE.md — mcp-google-calendar

MCP server for the Google Calendar API v3 (TypeScript, stdio). Mixed read/write: tools cover calendar listing, event CRUD + move, recurring-event instances, free/busy and Out of Office / Focus Time blocks; raw_request is the escape hatch. The server talks to https://www.googleapis.com (paths calendar/v3/...) with a Bearer token; the token is minted from an OAuth2 refresh token via https://oauth2.googleapis.com/token (or a static GOOGLE_CALENDAR_ACCESS_TOKEN, mostly for testing), or — when the environment carries no credentials — comes from the in-chat login of @a1-x-tech/mcp-google-auth (six onboarding tools; env always beats the stored login).

Commands

npm run dev        # run from source (tsx watch)
npm test           # unit tests + dist smoke, no network
npm run typecheck  # types for src + tests
npm run build      # emit dist/
npm run smoke      # live check: read-only by default; GOOGLE_CALENDAR_SMOKE_WRITE=1 opts into a disposable create→get→delete cycle with cleanup in finally

Architecture

• src/config.ts — env → config. Credentials: either the refresh triple GOOGLE_CALENDAR_CLIENT_ID + GOOGLE_CALENDAR_CLIENT_SECRET + GOOGLE_CALENDAR_REFRESH_TOKEN (all three or ConfigError incomplete_oauth_config) or GOOGLE_CALENDAR_ACCESS_TOKEN; optional GOOGLE_CALENDAR_API_BASE, GOOGLE_CALENDAR_TIMEOUT_MS, GOOGLE_CALENDAR_MAX_RETRIES. No credentials at all is NOT an error: the fields stay undefined and the server starts degraded. Also home to CredentialsError / MISSING_CREDENTIALS_MESSAGE (names the variables and the restart) and hasCredentials().
• src/client.ts — all HTTP and all wire mapping. Token lifecycle (cache until ~60s before expiry, dedupe concurrent refreshes, one forced re-mint + replay on 401); request() resolves the path against the base, rejects foreign origins (SSRF guard) and pins the resolved pathname under calendar/v3/ (www.googleapis.com hosts every Google API — a broadly-scoped token must not turn raw_request into a Drive/Gmail proxy), enforces an AbortController timeout that also covers reading the body, retries 429 always but 5xx/network errors only for GET — replaying a write after an ambiguous failure would duplicate the event and can re-email every guest — and throws GoogleCalendarError(status, body). Typed per-endpoint methods own the wire vocabulary: buildEventTimes()/buildEventBody() map the normalized snake_case inputs to the Event resource (all-day date pair XOR timed dateTime pair, Meet createRequest with a fresh requestId + conferenceDataVersion=1, reminders useDefault/overrides), and the mapping helpers translate send_updates (external_only → externalOnly), event_types (focus_time → focusTime), auto_decline (all → declineAllConflictingInvitations), chat_status (do_not_disturb → doNotDisturb) and min_access_role (free_busy_reader → freeBusyReader).
• src/tools/calendars.ts — list_calendars, get_calendar (calendarList reads). src/tools/events.ts — list_events, get_event, create_event, update_event (PATCH), delete_event, move_event (events.move), list_event_instances. src/tools/availability.ts — query_free_busy, create_out_of_office, create_focus_time (eventType events; Workspace primary calendars only). src/tools/raw.ts — raw_request (GET/POST/PUT/PATCH/DELETE). src/tools/util.ts — ok/fail, the four annotation presets (READ_ONLY/WRITE/UPDATE/DESTRUCTIVE) and shared zod schema factories (calendarIdSchema, eventIdSchema, rfc3339Timestamp, dateOnlySchema, timeZoneSchema, sendUpdatesSchema). src/tools/auth.ts — the in-chat login: AUTH_OPTIONS (serverName calendar, envPrefix GOOGLE_CALENDAR, the two minimal scopes, verifyIdentity = fetchCalendarIdentity in client.ts), registerAuthTools wraps the component's registerGoogleAuth (six tools: auth_status, setup_instructions, set_client, start_login — deliberately NOT read-only, finish_login, logout) and returns the TokenProvider the client takes as its fallback token source; hasAuthToken / authUnconfiguredPrefix feed index.ts.
• src/index.ts — wires every register* into the McpServer. loadConfigOrDegraded() catches ConfigError, pings startup_failed (fire-and-forget) and degrades the config to "no credentials"; an unconfigured start prepends UNCONFIGURED_PREFIX — plus Configuration problem: <message> when a ConfigError was caught — to the initialize instructions, and oninitialized sends server_start for a configured install or unconfigured_start (with the reason) otherwise.
• src/telemetry.ts — anonymous usage pings (ids/names/versions only, never data or arguments; fire-and-forget, must never block or throw; opt-out ASKADS_TELEMETRY=0; instance id in ~/.config/mcp-google-calendar/instance-id). server_start means "a usable install started"; unconfigured_start is a degraded start and startup_failed a malformed config caught at load — both carry a reason from a closed vocabulary (missing_credentials, incomplete_oauth_config) — never a variable's name or value.