Gmail MCP

An MCP server that lets Claude (Desktop, Code, or any MCP client) read, search, send, label, and manage your Gmail through OAuth2. 25 tools, batch operations, file-export for large result sets, retry-with-backoff, and OS-keyring token storage.

Highlights

• 25 tools across single, batch, and file-export families — see docs/TOOLS.md.

• Batch operations that bundle up to 100 Gmail calls per MCP request (read_emails, add_labels, archive_emails, …) for fast bulk workflows.

• File-export tools (read_emails_full, search_and_save, append_emails) save results to .md / .json / .jsonl / .csv so MCP output limits aren't hit when working with hundreds of emails.

• Resilient: exponential-backoff retry on 429/503, respects Retry-After, recovers from transient network failures.

• Secure token storage via OS keyring (optional) or filesystem (default).

• Tested: ~700 lines of unit tests, mocked Google client, no network in CI.

Quick start

pip install -e .                      # install in editable mode
# (or once published: pipx install gmail-mcp)

Then:

1. Get a credentials.json from Google Cloud Console — see docs/google-cloud-setup.md.

2. Place it at the OS config dir (~/.config/gmail-mcp/credentials.json on Linux/macOS, %APPDATA%\gmail-mcp\credentials.json on Windows).

3. Run gmail-mcp once in a terminal — it opens a browser for the OAuth flow and caches the token.

4. Register with Claude Desktop:

   mcp install src/gmail_mcp/server.py --name gmail-mcp

   Or, if you installed via pip, the gmail-mcp console script works too:

   mcp install $(which gmail-mcp) --name gmail-mcp

5. Restart Claude Desktop. Try: "List my 5 most recent unread emails."

Configuration

Set environment variables (or edit src/gmail_mcp/config.py):

OS-specific config dir defaults:

• Linux: ~/.config/gmail-mcp/

• macOS: ~/Library/Application Support/gmail-mcp/

• Windows: %APPDATA%\gmail-mcp\

To switch to OS keyring storage, set Config.token_storage = "keyring" in config.py and delete the cached token.json so the OAuth flow re-runs.

Tools at a glance

Full parameter reference and examples: docs/TOOLS.md.

Documentation

• docs/google-cloud-setup.md — step-by-step OAuth client setup.

• docs/ARCHITECTURE.md — module map, request flow, design decisions.

• docs/TROUBLESHOOTING.md — common errors and fixes.

• docs/TOOLS.md — every tool, every parameter, every response.

Contributing

See CONTRIBUTING.md for dev setup, tests, and the PR checklist. Bug reports and feature requests welcome via GitHub Issues.

License

MIT.