gmail-mcp-server: Instructions file for Gemini CLI

CLAUDE.md

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

What This Repo Is

Two loosely coupled systems that share the Gmail API client:

1. MCP Server (gmail_mcp_server/) — a stdio MCP server exposing Gmail tools to AI assistants (Claude, Gemini). Runs headlessly via .mcp.json.
2. Web Dashboard (app.py) — a Flask app that invokes triage by spawning gemini -p /triage as a subprocess, parses the structured output, and caches results for the browser UI.

The triage command itself lives in commands/triage.md (symlinked into .claude/commands/ and converted to .gemini/commands/ TOML). The command instructs the AI to call Gmail MCP tools directly.

Commands

# Auth setup (requires credentials.json from Google Cloud Console)
make auth

# Run tests
python -m pytest                        # all tests
python -m pytest tests/test_server.py  # single file
python -m pytest -k "test_format"      # single test pattern

# Start web dashboard (auto-restarts on crash)
make dashboard

# Run triage manually
make triage MODEL=haiku     # default; also: sonnet, opus
make watch MODEL=haiku      # run every 5 min

# Dashboard PIN management
make set-pin

# Re-link slash commands after editing commands/*.md
make link-commands

# Container
make podman-build
make podman-push

Architecture

MCP Server (gmail_mcp_server/)

• server.py — GmailMCPServer wraps mcp.server.Server. Maintains an in-memory position map (email_position_map) that maps 1-based integer positions (shown in list_unread_emails output) to Gmail message IDs. This map is rebuilt on every list_unread_emails call, so tools like delete_emails and archive_emails accept positions[] referencing the last fetch. Also holds an in-memory action log (capped at 100).
• gmail_client.py — GmailClient wraps google-api-python-client. Auth is lazy: _ensure_authenticated() is called before every API call. Token is read from token.json; interactive OAuth only runs when GMAIL_INTERACTIVE_AUTH=1. modify_labels automatically removes all other Triage/* labels when a new one is added — this enforces the one-label-per-email invariant.
• auth.py — standalone auth helper invoked by make auth.