google-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.

Commands

pnpm install          # Install dependencies
pnpm build            # Compile TypeScript → dist/
pnpm dev              # Run with hot reload (tsx watch)
pnpm test             # Run all tests (watch mode)
pnpm test:coverage    # Run tests with coverage report
pnpm lint             # ESLint check
pnpm lint:fix         # ESLint auto-fix

Run a single test file:

pnpm vitest run src/__tests__/gmail.test.ts

Run a single test by name:

pnpm vitest run --reporter=verbose -t "should get user profile"

Architecture

Entry & Server

src/index.ts → src/server.ts (GoogleWorkspaceMCPServer) is the single MCP server. It registers all tools in two handlers:

• ListToolsRequestSchema — returns tool definitions with Zod-derived JSON schemas
• CallToolRequestSchema — dispatches tool name → service method call

Services are lazily initialized in initializeServices(), called only after OAuth is confirmed ready via ensureAuthenticated().

Auth

src/auth/oauth.ts exports a singleton oauth instance (GoogleOAuth). It handles:

• Reading credentials.json from platform-specific config dirs (~/Library/Application Support/google-mcp/ on macOS)
• Storing/refreshing tokens at the same location as tokens.json
• Starting a local HTTP callback server on ports 3000–3100 for OAuth redirect

Services

Each file in src/services/ wraps one Google API. Services take an Auth.OAuth2Client in the constructor and call googleapis directly. There is no shared base class.

File	Google API
calendar.ts	Calendar v3
gmail.ts	Gmail v1
drive.ts	Drive v3
docs.ts	Docs v1
sheets.ts	Sheets v4
slides.ts	Slides v1
forms.ts	Forms v1
chat.ts	Chat v1
meet.ts	Meet v2
people.ts	People v1 (Contacts)
tasks.ts	Tasks v1
youtube.ts	YouTube Data v3