How takumi0706/google-calendar-mcp works
Project type and purpose
• This is a backend “tool‐style” microservice: a Model Context Protocol (MCP) server that runs over STDIO, plugs into Claude Desktop, and exposes Google Calendar operations as “tools.”
• Its purpose is to mediate between Claude Desktop and the Google Calendar API, handling OAuth2, schema validation, event CRUD, and token security.
High-level file‐structure analysis
• Top level: configuration files, CI/CD workflows, test config (jest.config.js), TS config.
• src/ directory is organized into feature-driven subdirectories:
• auth/ – OAuth handlers, token manager
• calendar/ – calendar-specific API wrappers and types
• config/ – environment-based config loader
• mcp/ – MCP server core (transport, tool registration, JSON‐RPC handling)
• utils/ – logging, error handling, HTML sanitization, JSON parsing
• __tests__/ – unit tests mirroring each feature directory
• Key external configs: .env.example (dotenv), qodana.yaml (code quality), GitHub Actions YAMLs (CI/CD pipelines).
Architecture insights from README
• Core components outlined: MCP Server, Google Calendar Tools, Auth Handler, Schema Validation, Token Manager
• Tech stack: TypeScript, @modelcontextprotocol/sdk, googleapis, Zod, Helmet.js, AES-256-GCM, Jest, GitHub Actions
• Communication: STDIO transport for MCP JSON‐RPC messages
Diagramming the system – main components and interactions
1. CLAUDE DESKTOP (External System)
• Initiates STDIO connection, sends MCP JSON‐RPC requests
2. STDIO TRANSPORT LAYER (src/mcp/server.ts)
• Reads/writes to process.stdin/stdout
• Invokes MCP SDK message parsing
3. MCP SERVER CORE (@modelcontextprotocol/sdk)
• Registers tools, dispatches incoming tool calls based on Model Context Protocol
4. TOOL IMPLEMENTATIONS
– Google Calendar Tools (src/calendar/calendar-api.ts)
– CRUD functions: getEvents, createEvent, updateEvent, deleteEvent, authenticate
5. AUTHENTICATION SUBSYSTEM
• oauth-handler.ts: spins up local HTTP server for OAuth code exchange
• token-manager.ts: encrypts/decrypts tokens in memory using AES-256-GCM
6. SCHEMA VALIDATION (src/mcp/schemas.ts, zod)
• Validates incoming parameters and outgoing responses
7. CONFIGURATION (src/config/config.ts, dotenv)
• Loads env vars: client ID/secret, ports, encryption key, manual auth flag
8. UTILITIES
• Logger, error-handler, html-sanitizer, json-parser
9. GOOGLE CALENDAR API (External Service)
• Receives authenticated HTTP requests from calendar-api.ts
• Claude Desktop → STDIO Transport → MCP SDK → Tool Dispatcher
• Tool Dispatcher → Schema Validation → Appropriate Tool Function
• Tool Function → (if auth needed) → Token Manager & OAuth Handler → Google API
• Tool Function → Google API → returns data → Schema Validation → MCP SDK → STDIO → Claude Desktop
• Config module is imported by all internal modules (auth, mcp, calendar, utils)
• Utils are imported wherever logging, error handling, or parsing is needed
c. Architectural patterns & design principles
• Layered structure: transport → protocol core → business logic → external API
• Separation of concerns: auth, validation, tools, config, utils
• Dependency injection via configuration module
• Secure-by-design: in‐memory tokens, AES-256-GCM encryption, Helmet.js headers, Zod validation
d. Key technologies, frameworks, libraries
• TypeScript (static typing)
• @modelcontextprotocol/sdk (MCP server core)
• googleapis (Google Calendar integration)
• Zod (schema validation)
• dotenv (config)
• AES-256-GCM (crypto)
• Helmet.js (security headers)
• Jest (unit testing)
• GitHub Actions (CI/CD)
Detailed capturing of architectural elements
• Sequence for a typical tool call (e.g., createEvent): STDIO → MCP → validate → auth (if needed) → calendar-api → Google API → back through validation and STDIO