oauth2-authenticated google calendar api bridge via mcp protocol
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.
Unique: Uses MCP protocol's standardized tool registry pattern (BaseToolHandler + ToolRegistry.getTools()) combined with Zod schema validation to automatically generate JSON schemas from TypeScript types, eliminating manual schema maintenance and enabling type-safe tool invocation across multiple transport modes (stdio and HTTP)
vs alternatives: More secure than direct API key storage and more flexible than hardcoded OAuth flows because it abstracts authentication into a reusable MCP component that works across Claude Desktop, Docker, and custom clients without code changes
multi-transport mcp server deployment (stdio and http modes)
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.
Unique: Abstracts transport layer through MCP SDK's built-in transport handlers, allowing identical tool registry and authentication logic to work across stdio and HTTP without conditional branching in business logic — transport selection is purely a configuration concern in main()
vs alternatives: More flexible than single-transport MCP servers because it supports both local (Claude Desktop) and remote (Docker/Kubernetes) deployment from one codebase, whereas most community MCP servers are hardcoded to stdio mode
timezone-aware event scheduling with automatic conversion
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.
Unique: Leverages RFC 3339 timestamp format to embed timezone information directly in event times, eliminating the need for separate timezone parameters and enabling automatic conversion to user's calendar timezone
vs alternatives: More robust than manual timezone conversion because it relies on RFC 3339's standardized timezone representation, whereas manual conversion logic is error-prone and doesn't account for daylight saving time transitions
docker deployment with http transport and environment-based configuration
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.
Unique: Provides docker-compose.yml template with HTTP transport and environment-based configuration, enabling one-command remote deployment without manual Docker setup
vs alternatives: Simpler than manual Docker configuration by providing a template, reducing deployment friction for cloud environments
registry-based tool definition generation with zod schema validation
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.
Unique: Uses Zod's runtime schema introspection to automatically derive MCP JSON schemas from TypeScript type definitions, creating a single source of truth for both validation and schema generation — eliminates the dual-maintenance problem of keeping TypeScript types and JSON schemas in sync
vs alternatives: More maintainable than manually-written JSON schemas because schema changes in Zod automatically propagate to MCP definitions, whereas competing MCP servers often maintain separate TypeScript types and JSON schema files that drift out of sync
event creation and updating with conflict detection and attendee management
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.
Unique: Implements conflict detection by querying the target calendar's event list before creation, comparing time ranges to identify overlaps, and surfacing warnings to the AI assistant — this enables the LLM to make informed scheduling decisions rather than blindly creating conflicting events
vs alternatives: More intelligent than basic event creation APIs because it provides conflict awareness and attendee management in a single tool, whereas raw Google Calendar API requires separate queries and manual conflict resolution logic
calendar enumeration and event search with date range filtering
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.
Unique: Separates calendar discovery (list-calendars) from event retrieval (search-events) into distinct tools with independent schemas, allowing AI assistants to first understand available calendars before querying events — this two-step pattern prevents errors from invalid calendar IDs and enables context-aware scheduling
vs alternatives: More discoverable than raw Google Calendar API because it exposes calendar enumeration as a separate tool, whereas most calendar integrations require users to manually specify calendar IDs
reminder and notification configuration with flexible timing options
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.
Unique: Abstracts Google Calendar's reminder API by accepting human-readable time intervals (minutes before event) and automatically converting to Google's notification format, hiding the complexity of Google's reminder schema from the AI assistant
vs alternatives: More user-friendly than raw Google Calendar API because it accepts intuitive time intervals (e.g., '15 minutes before') instead of requiring knowledge of Google's notification type enums and delivery mechanisms
+4 more capabilities