mcp-google-gmail: Instructions file for Claude Code

CLAUDE.md — mcp-google-gmail

MCP server for the Gmail API v1 (TypeScript, stdio). Mixed read/write: tools cover message/thread search and decoded reading, sending (direct and via drafts), the full draft lifecycle, labels and the reversible trash; raw_request is the escape hatch. The server talks to https://gmail.googleapis.com (always users/me — one mailbox) with a Bearer token; the token is minted from an OAuth2 refresh token via https://oauth2.googleapis.com/token (or a static GOOGLE_GMAIL_ACCESS_TOKEN, mostly for testing). There is deliberately no permanent message delete — the trash is the safety net.

Commands

npm run dev        # run from source (tsx watch)
npm test           # unit tests + dist smoke, no network
npm run typecheck  # types for src + tests
npm run build      # emit dist/
npm run smoke      # live check: read-only profile fetch; GOOGLE_GMAIL_SMOKE_WRITE=1 adds a disposable-draft roundtrip with cleanup in finally

Architecture

• src/config.ts — env → config. Credentials: either the refresh triple GOOGLE_GMAIL_CLIENT_ID + GOOGLE_GMAIL_CLIENT_SECRET + GOOGLE_GMAIL_REFRESH_TOKEN (all three or ConfigError incomplete_oauth_config) or GOOGLE_GMAIL_ACCESS_TOKEN; optional GOOGLE_GMAIL_API_BASE, GOOGLE_GMAIL_TIMEOUT_MS, GOOGLE_GMAIL_MAX_RETRIES. No credentials at all is NOT an error: the fields stay undefined and the server starts degraded. Also home to CredentialsError / MISSING_CREDENTIALS_MESSAGE (opens with the historical startup error verbatim, then names the variables and the restart) and hasCredentials().
• src/client.ts — all HTTP and all wire mapping. Token lifecycle (cache until ~60s before expiry, dedupe concurrent refreshes, one forced re-mint + replay on 401); request() resolves the path against the base and rejects foreign origins (SSRF guard), enforces an AbortController timeout that also covers reading the body, retries 429 always but 5xx/network errors only for GET — replaying a send after an ambiguous failure would double-send — and throws GoogleGmailError(status, body). The MIME layer lives here too: buildMimeMessage() (RFC 2822 with base64 bodies, multipart/alternative, RFC 2047 subject, header-injection guard, reply headers) and decodeMessage() (base64url + charset decode, RFC 2047 header decode, attachment metadata, maxBodyChars truncation with flags). buildLabelChanges() maps the normalized read/starred/archived flags to UNREAD/STARRED/INBOX label operations.
• src/tools/messages.ts — list_messages (search + metadata hydration), get_message, send_message, modify_message, manage_trash (trash/untrash × message/thread). src/tools/threads.ts — list_threads, get_thread, modify_thread. src/tools/drafts.ts — create_draft, list_drafts, get_draft, update_draft (full replacement — the API has no partial draft edit), send_draft, delete_draft (permanent — drafts skip the trash). src/tools/labels.ts — list_labels (list, or one label with counts), manage_labels (create/update/delete). src/tools/profile.ts — get_profile. src/tools/raw.ts — raw_request (GET/POST/PUT/PATCH/DELETE). src/tools/util.ts — ok/fail, the four annotation presets (READ_ONLY/WRITE/UPDATE/DESTRUCTIVE) and shared zod schema factories (messageIdSchema, recipientSchema, gmailQuerySchema, ...).
• src/index.ts — wires every register* into the McpServer. loadConfigOrDegraded() catches ConfigError, pings startup_failed (fire-and-forget) and degrades the config to "no credentials"; an unconfigured start prepends UNCONFIGURED_PREFIX — plus Configuration problem: <message> when a ConfigError was caught — to the initialize instructions, and oninitialized sends server_start for a configured install or unconfigured_start (with the reason) otherwise.
• src/telemetry.ts — anonymous usage pings (ids/names/versions only, never mail or arguments; fire-and-forget, must never block or throw; opt-out ASKADS_TELEMETRY=0). server_start means "a usable install started"; unconfigured_start is a degraded start and startup_failed a malformed config caught at load — both carry a reason from a closed vocabulary (missing_credentials, incomplete_oauth_config) — never a variable's name or value.