google-calendar-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Google Calendar MCP Server is an MCP (Model Context Protocol) implementation that enables Claude Desktop to interact with Google Calendar through natural language. The server uses OAuth2 authentication and provides tools for managing calendar events (get, create, update, delete).

Code Style

• All code comments, JSDoc, and documentation must be written in English
• Variable names, function names, and other identifiers should use English
• Git commit messages and pull request descriptions must be written in English

Development Commands

Building and Running

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Run in development mode (uses ts-node, no build required)
npm run dev

# Run production build
npm start

Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm test -- path/to/test.test.ts

Code Quality

# Run ESLint
npm run lint

# Format code with Prettier
npm run format

# Run security audit
npm run security

Version Management

When making changes, use semantic versioning:

npm version patch|minor|major

Architecture

Core Flow

1. Entry Point (src/index.ts): Initializes OAuth authentication, then starts MCP server with STDIO transport
2. Authentication (src/auth/): OAuth2 flow with on-demand server startup/shutdown
3. MCP Server (src/mcp/server.ts): Registers tools, resources, and prompts via STDIO transport
4. Tools Execution (src/mcp/tools.ts): Validates parameters with Zod, calls Calendar API
5. Calendar API (src/calendar/calendar-api.ts): Google Calendar API wrapper using googleapis

Key Architectural Patterns

Authentication Flow:

• OAuth server starts on-demand when authentication is needed (port 4153 by default)
• After successful authentication, server shuts down to free the port
• Supports two modes: automatic (opens browser) and manual (user enters code)
• Token refresh handled automatically; re-authentication initiated if refresh token unavailable
• Tokens stored in-memory via TokenManager with AES-256-GCM encryption