How nspady/google-calendar-mcp works
Project Type and Purpose
• This is a backend MCP (Model Context Protocol) server that exposes a standardized API for LLMs (e.g., Claude Desktop) to interact with Google Calendar.
• Purpose: handle OAuth, translate MCP commands into calls to the Google Calendar API, and return structured results.
File Structure
• Top‐Level Files & Configs
– Dockerfile, .dockerignore → containerization
– github/workflows/ci.yml → CI pipeline
– package.json, tsconfig.json, bun.lockb → Node.js/TypeScript project
• src/auth‐server.ts & src/auth/
– Implements local OAuth server to obtain/refresh tokens
• src/index.ts
– Entry point: bootstraps authentication check, starts MCP HTTP/CLI server
• src/handlers/
– callTool.ts: dispatches incoming MCP commands
– core/*.ts: per‐command handlers (ListEvents, CreateEvent, etc.)
• src/schemas/
– Types & validation for incoming/outgoing messages
• scripts/build.js
– Custom build steps, e.g., bundling or assets
Extract Key Insights from README
• External Dependencies: Google Calendar API, OAuth 2.0
• Runtime Flow:
1. Server startup → check tokens → if missing, spin up a temporary OAuth HTTP server (ports 3000–3004)
2. Browser consent → tokens saved to .gcp-saved-tokens.json
3. Server initializes MCP endpoints
• Integration Point: LLMs invoke the MCP server via CLI or HTTP (defined in Claude Desktop config)
Main Architectural Components
a. OAuth Module
• Subcomponents:
• Credentials Loader (reads gcp-oauth.keys.json)
• Token Storage (.gcp-saved-tokens.json)
• Local HTTP Auth Server (src/auth-server.ts + src/auth/server.ts)
b. MCP Core Server
• Entry (src/index.ts)
• Router / Dispatcher (callTool.ts)
• Handler Layer (each core/* Handler)
c. Schema & Validation
• Types (types.ts)
• Validators (validators.ts)
d. External Systems
• Google Calendar REST API
• External Client (LLM or CLI)
• (Optional) Docker container or hosting environment
e. CI/CD & Deployment
• GitHub Actions CI (ci.yml)
• Dockerfile for container image
Relationships & Data Flows
• Startup (arrowed flow):
1. MCP Server boot → check token store →
2. If needed, spawn OAuth HTTP Server → User’s browser → Google Auth → Redirect to local callback → token written
3. MCP Server ready
• Request Handling:
• External Client → MCP Server (callTool endpoint) → Dispatcher
• Dispatcher → Appropriate Handler → uses Token Manager to call Google Calendar API
• Handler receives Google API response → applies schema/validation → returns response to client
Architectural Patterns & Principles
• Modular Handler Pattern: one handler per calendar operation
• Single Responsibility: separate modules for auth, dispatch, handlers, schemas
• Configurable OAuth Flow: ports range, token persistence
• Testability: mocks for Google API and filesystem in Vitest tests
• Component labels: “OAuth Server”, “Token Manager”, “MCP Dispatcher”, “Calendar Handlers”