gmail-mcp

Minimal Gmail MCP server for Claude Code. Zero third-party code — only official Google and Anthropic libraries.

Tools

Tool	Description
search_emails	Search with Gmail query syntax (is:unread, from:x, after:2026/03/01)
read_email	Read full email by ID (headers + plain text body, HTML fallback)
read_thread	Read all messages in a thread
mark_as_read	Mark one or more emails as read
mark_as_unread	Mark one or more emails as unread
send_email	Send email (to, cc, bcc, subject, body)
create_draft	Create draft without sending
reply	Reply to a thread (supports reply-all)
list_labels	List all labels with unread counts

Architecture

gmail-mcp/
├── server.py          # FastMCP server — 9 tools, stdio transport
├── auth.py            # OAuth2 flow + credential management
├── gmail_tools.py     # Gmail API wrapper functions
├── requirements.txt   # 3 dependencies (all official)
├── setup.sh           # Create venv + install + first-time OAuth
├── .env.example       # Template for OAuth credentials
└── .gitignore

• Transport: stdio (standard for Claude Code MCPs)
• Auth: OAuth2 with gmail.modify scope (covers read + modify + send)
• Multi-account: Two instances in ~/.claude.json with different env vars
• Token storage: ~/.gmail-mcp/{email}.json per account, 0600 permissions

Setup

1. Google Cloud Console

• Enable the Gmail API in your GCP project
• Create an OAuth 2.0 Client ID (Desktop application)
• Add https://www.googleapis.com/auth/gmail.modify to allowed scopes

2. Install

git clone https://github.com/fernandezdiegoh/gmail-mcp.git
cd gmail-mcp
cp .env.example .env
# Edit .env with your OAuth credentials
bash setup.sh

setup.sh creates the venv, installs deps, and runs the browser OAuth flow.

3. Register in Claude Code

Add to ~/.claude.json under "mcpServers":

"gmail": {
  "type": "stdio",
  "command": "/path/to/gmail-mcp/.venv/bin/python3",
  "args": ["/path/to/gmail-mcp/server.py"],
  "env": {
    "GOOGLE_OAUTH_CLIENT_ID": "your-client-id",
    "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret",
    "USER_EMAIL": "you@example.com",
    "CREDENTIALS_DIR": "~/.gmail-mcp"
  }
}

Multi-account

Register multiple instances with different keys (e.g., gmail and gmail-personal) pointing to the same server.py but different env vars. Each account gets its own token file in CREDENTIALS_DIR.

Dependencies

Package	Purpose	Source
mcp	MCP SDK (FastMCP)	Anthropic (official)
google-auth-oauthlib	OAuth2 flow	Google (official)
google-api-python-client	Gmail API client	Google (official)

Requirements

• Python 3.10+

License

MIT