Google Calendar MCP Server

Implements a registry pattern where each calendar operation extends BaseToolHandler and generates MCP-compatible tool definitions with JSON schemas derived from Zod validation schemas. The ToolRegistry.getTools() method transforms handler classes into standardized tool definitions that conform to the Model Context Protocol specification, enabling AI assistants to discover and invoke calendar operations with type-safe argument validation.

Implements Google OAuth2 flow by spawning a temporary HTTP server via runAuthServer() in src/auth-server.ts that handles the authorization callback, then persists tokens to the user's config directory for automatic refresh during tool execution. The authentication system intercepts API calls, checks token expiration, and transparently refreshes credentials without requiring user re-authentication, enabling seamless long-lived calendar access.

Provides claude_desktop_config.json configuration template that enables Claude Desktop to discover and invoke the MCP server via stdio transport. The configuration specifies the server command (npx or local build), arguments (--transport stdio), and environment variables for OAuth credentials, allowing Claude Desktop to spawn the MCP server as a subprocess and communicate via stdin/stdout.

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.

Supports two transport modes configured via --transport CLI argument in src/index.ts: stdio mode for local process communication with Claude Desktop, and HTTP mode providing REST endpoints and Server-Sent Events for remote integration. The main() function initializes the appropriate transport handler based on configuration, enabling the same calendar tool registry to serve both local and remote MCP clients without code duplication.

Provides list-calendars and list-events tools that query Google Calendar API with optional date range filtering (startTime, endTime) and calendar selection. The implementation handles timezone-aware datetime parsing, pagination through large result sets, and formatting of event metadata (title, time, attendees, reminders) into human-readable output suitable for AI assistant context.

Implements create-event tool that accepts event details (title, start/end times, description, attendees, reminders) and performs intelligent conflict detection by querying existing events in the target calendar before insertion. The tool supports adding multiple attendees with optional RSVP notifications, setting reminder configurations (popup, email), and returning the created event ID for subsequent updates or deletions.

Provides update-event tool that modifies existing events by eventId with support for partial updates (only changed fields are sent to API). The tool accepts optional parameters for title, start/end times, description, attendees, and reminders, applying only non-null values to the target event while preserving unchanged fields. This approach minimizes API payload size and reduces risk of accidentally overwriting fields.

Provides delete-event tool that removes events from calendar by eventId with optional confirmation messaging. The tool calls Google Calendar API's delete endpoint and returns confirmation of successful deletion, enabling AI assistants to remove unwanted events or handle cancellation workflows.

Handles recurring events by expanding recurrence rules (RRULE) into individual event instances within queried date ranges, parsing recurrence patterns (daily, weekly, monthly, yearly) with frequency, interval, and end date constraints. The system automatically expands recurring events when listing or searching, presenting each instance as a separate event to the AI assistant while maintaining reference to the parent recurring event.

Provides search-events tool that queries events by date range with optional text search on event titles and descriptions. The tool accepts ISO 8601 datetime parameters and returns matching events with full metadata, enabling AI assistants to find specific events or check availability for scheduling. The search integrates with the event listing infrastructure to support filtering across multiple calendars.

Implements BaseToolHandler framework that wraps Google Calendar API calls with consistent error handling, response formatting, and logging. Each tool handler extends BaseToolHandler, executes the corresponding API operation, catches Google API errors (authentication failures, rate limits, invalid parameters), and formats responses into human-readable text suitable for AI assistant consumption. The framework provides standardized error messages and retry logic for transient failures.