gmail-mcp CLAUDE.md

Gmail MCP — Development Guide

What it is

A local stdio MCP server giving an AI agent unified access to multiple Gmail accounts at once. The native Anthropic Gmail connector binds one account per OAuth grant; this server holds refresh tokens for N accounts in a local SQLite store and routes each tool call to the right inbox via an account argument. search_all_accounts fans one query across every inbox.

Layout

src/gmail_mcp/
  server.py   — MCP server entry point, tool registration, dispatch, per-account routing
  auth.py     — gmail-mcp-auth CLI: browser OAuth bootstrap (NOT an MCP tool)
  store.py    — SQLite token store (accounts table keyed by email)
  gmail.py    — per-account service build + token refresh; pure MIME parsing/formatting
  config.py   — path resolution (DB, client secret) + SCOPES constant
tests/        — pytest; Gmail client is mocked, no live network

Module responsibilities

Module	Purpose
server.py	Registers MCP tools, dispatches calls, resolves account → service. All Gmail network I/O runs in asyncio.to_thread (the google client is sync).
auth.py	add / list / remove subcommands. add runs InstalledAppFlow.run_local_server, reads the granted email from users.getProfile, upserts into the store.
store.py	TokenStore CRUD over sqlite3. upsert preserves added_at; touch stamps last_used_at; update_token persists refreshed access tokens.
gmail.py	build_service(account, store) builds google-auth Credentials, refreshes if stale, persists the new token, returns a Gmail client. Plus pure helpers — parse_message, extract_body_and_attachments, strip_html, resolve_label_ids, build_mime_message, sanitize_filename, screen_attachment, decode_b64url_bytes, formatters.
config.py	db_path(), client_secret_path(), attachments_dir(), max_attachment_bytes(), SCOPES.

OAuth model

• Auth is a CLI, not a tool — the OAuth flow needs a browser, which an MCP tool can't drive. gmail-mcp-auth add runs the installed-app loopback flow and stores the refresh token.
• Client config comes from a downloaded Google "Desktop app" OAuth client JSON at ~/.gmail-mcp/client_secret.json (env GMAIL_MCP_CLIENT_SECRET). Never hardcode client_id/client_secret.
• Token store: SQLite at ~/.gmail-mcp/tokens.db (env GMAIL_MCP_DB). Keyed by email. Holds refresh_token + last access-token blob + scopes.
• Refresh: google-auth's Request transport refreshes the access token on demand; build_service persists the refreshed blob back to the DB.
• Scopes (one constant, config.SCOPES): gmail.readonly, gmail.compose, gmail.modify, gmail.settings.basic. Granular — NOT full mail.google.com, and no gmail.send / no gmail.settings.sharing (see Security model). Widening SCOPES does NOT retro-grant existing accounts — each must re-run gmail-mcp-auth add to re-consent, or the new tool returns 403 insufficient scope.