Google Calendar MCP Server

Implements a stateful OAuth2 authentication system that spawns a temporary HTTP server (runAuthServer() in src/auth-server.ts) to handle Google's authorization flow, persists tokens to the user's config directory, and automatically refreshes credentials during tool execution. The MCP protocol layer translates all calendar operations into standardized tool definitions with Zod-validated JSON schemas, enabling AI assistants to invoke calendar functions through a unified interface without direct API knowledge.

Provides dual transport layer implementation where the main() function in src/index.ts routes between stdio mode (for local clients like Claude Desktop using process communication) and HTTP mode (for remote deployment with REST endpoints and Server-Sent Events). This architecture enables the same tool registry and authentication system to serve both local and distributed clients without modification, with deployment configuration managed via --transport CLI argument and docker-compose.yml for containerized setups.

Handles timezone-aware event creation by accepting RFC 3339 timestamps (which include timezone information) and automatically converting them to the user's calendar timezone. The system stores events in Google Calendar with timezone metadata, enabling correct display across different timezones and preventing scheduling errors when users or attendees are in different regions. Event times are returned in RFC 3339 format with timezone information, enabling AI assistants to display times correctly to users in any timezone.

Supports Docker containerization via docker-compose.yml that runs the MCP server in HTTP mode with environment variable configuration for OAuth credentials and port binding. The Docker setup enables remote deployment of the MCP server with automatic container orchestration, health checks, and volume mounting for persistent token storage. HTTP transport allows multiple remote clients to connect via REST endpoints and Server-Sent Events.

Implements a tool registry pattern (ToolRegistry class in src/tools/registry.ts) where each calendar operation extends BaseToolHandler and declares its input schema using Zod validators. The ToolRegistry.getTools() method introspects these Zod schemas at runtime to generate MCP-compatible JSON schema definitions, ensuring type safety between the AI assistant's tool invocation and the handler's execution logic. This eliminates manual schema maintenance and enables automatic validation of tool inputs before execution.

Provides structured event management through handler classes that accept Zod-validated inputs (title, start/end times, description, attendees, reminders) and execute Google Calendar API calls to create or update events. The implementation includes intelligent conflict detection that queries existing events in the target calendar to warn about scheduling overlaps, and supports multi-attendee management with RSVP status tracking. Recurring event handling is managed through Google Calendar's recurrence rule (RRULE) format, enabling complex repeat patterns without custom scheduling logic.

Exposes list-calendars and search-events tools that query the Google Calendar API to enumerate all calendars accessible to the authenticated user and retrieve events within specified date ranges. The search-events tool accepts start and end timestamps (RFC 3339 format) and returns matching events with full details (title, time, attendees, description). This enables AI assistants to understand the user's calendar landscape and retrieve relevant events for decision-making without loading the entire calendar history.

Supports reminder management through event creation/update tools that accept reminder specifications (time before event, notification type). Reminders are stored in Google Calendar's reminder system and delivered via email or popup notifications based on user preferences. The implementation accepts reminder times in minutes before the event (e.g., 15 minutes, 1 day = 1440 minutes) and maps them to Google Calendar's notification API format, enabling AI assistants to set up notifications without understanding Google's internal reminder schema.

Implements recurring event creation and management by accepting recurrence rules in RFC 5545 RRULE format (e.g., 'FREQ=WEEKLY;BYDAY=MO,WE,FR') and passing them directly to Google Calendar's API. The system handles complex recurrence patterns including frequency (daily, weekly, monthly, yearly), day-of-week constraints, interval counts, and end dates. Modifications to recurring events are managed through Google Calendar's instance-level updates, enabling changes to specific occurrences without affecting the entire series.

Manages event attendees through event creation and update tools that accept attendee email lists and track RSVP responses from Google Calendar's attendee system. When events are created or updated with attendees, Google Calendar automatically sends invitations and tracks responses (accepted, declined, tentative, no response). The system exposes attendee lists in event details, enabling AI assistants to understand who has accepted meetings and who hasn't responded. Attendee management is handled through Google Calendar's native attendee API without custom RSVP logic.

Provides event deletion capability through a delete-event tool that removes events from Google Calendar. For recurring events, the tool supports three deletion modes: delete single instance, delete this and all future instances, or delete entire series. The implementation handles Google Calendar's instance-level deletion semantics, where deleting a single occurrence of a recurring event creates an exception in the series rather than removing the entire series. This enables precise control over recurring event modifications without unintended side effects.

Supports rich event descriptions through event creation and update tools that accept formatted text descriptions, enabling AI assistants to include meeting agendas, notes, links, and other contextual information. The system stores descriptions as plain text or formatted strings in Google Calendar's event description field, with utility functions in src/tools/events/utils.ts handling formatting and parsing. Event metadata (title, location, description) is returned in search results, enabling AI assistants to provide detailed event information to users.