This is a Model Context Protocol (MCP) server written in TypeScript that exposes Gmail as a set of tools an LLM client (like Claude Desktop or Claude Code) can call. It runs locally on the user's machine over stdio and authenticates to Gmail via Google OAuth2, then translates MCP tool calls into Gmail API requests through the official googleapis SDK.

The problem it solves is that LLMs on their own cannot access a user's Gmail account. Without a bridge like this, an assistant cannot read inbox messages, send email, manage labels, apply filters, download attachments, or reply in-thread. This server provides that bridge with a lean, focused surface area: sending, reading, searching, threading, labels, filters, drafts, and phishing/spam reporting.

The intended users are individual developers who use Claude (Desktop or Code) as a daily driver and want the assistant to act on their personal or work Gmail. The README explicitly frames it as a personal-use tool run on the user's own machine, not a hosted multi-tenant service. Install is via `npx @artymclabin/gmail-mcp auth` or by cloning and building; auth uses a `gcp-oauth.keys.json` file the user obtains from Google Cloud Console.

Under the hood, `src/index.ts` wires up the MCP SDK server, `src/tools.ts` declares every tool (with Zod schemas and MCP annotations like `readOnlyHint`/`destructiveHint`), and dedicated modules handle sub-domains: `filter-manager.ts` for filters, `label-manager.ts` for labels, `email-export.ts` for downloading emails to json/eml/txt/html, `reply-all-helpers.ts` for threading, and `scopes.ts` for OAuth scope-based tool filtering. `nodemailer` is used to construct MIME messages (including multipart/related for inline images), and `googleapis` handles the actual Gmail API calls. Refresh tokens are persisted so sessions survive restarts.

Notable positive signals: extensive vitest test coverage (delete-scopes, download-email, inline-images, phishing-tools, reply-all, thread-tools, tool-prefix, utl), CI workflow, lockfile-lint, MCP tool annotations, least-privilege scope gating (permanent delete requires opt-in `gmail.full`), documented security fixes (path traversal, shell injection in CI, CVE dependency bumps), and a candid README that credits every contributor PR. No obfuscation, no telemetry, no network calls beyond Google APIs. Behavior matches the stated purpose.