mcp-google-sheets: Instructions file for Claude Code

CLAUDE.md

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

Overview

An MCP (Model Context Protocol) stdio server that gives AI agents read/write access to Google Spreadsheets. Two auth modes, auto-detected from env: per-user OAuth (browser sign-in, edits attributed to the real user) or Service Account (headless JWT, legacy). There is no fixed target spreadsheet — every tool takes a required spreadsheet parameter (URL or ID). Written in TypeScript, ESM-only, bundled with tsup.

Commands

npm run dev      # Run directly from TypeScript via tsx (no build) — primary dev loop
npm run build    # Bundle src/index.ts → dist/index.js with tsup
npm start        # Run the built server (node dist/index.js)

npm run typecheck     # tsc --noEmit (type validation)
npm run lint          # eslint .
npm run format        # prettier --write . (format:check to verify without writing)

npx tsx src/test-tools.ts <spreadsheet-url-or-id>   # Manual end-to-end test: hits a REAL Google Sheet

There is no unit test framework. Linting (ESLint flat config, eslint.config.js), formatting (Prettier, .prettierrc.json — single quotes, markdown ignored) and typechecking scripts exist; run them before committing. test-tools.ts is a manual integration harness that runs every tool handler against the live spreadsheet passed as argv[2] (or TEST_SPREADSHEET env). It creates a TestTab_<timestamp> sheet and writes rows — expect side effects on the real sheet. Run it to verify changes end-to-end.

Requires a .env (copy .env.example) with ONE auth mode:

• OAuth: GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET (wins if both modes are set)
• Service Account: GOOGLE_SERVICE_ACCOUNT_EMAIL + GOOGLE_PRIVATE_KEY

Optional: TOOLS (comma-separated allowlist), USER_NAME (stamped onto add_rows writes). SPREADSHEET_ID no longer exists.

Architecture

Startup flow (src/index.ts): loadConfig() → new AuthManager(config) → new SheetsClient(authManager) → registerAllTools(server, client, config) → connect stdio transport. Diagnostics go to console.error (stdout is reserved for the MCP protocol — never write to it, and never prompt on it).