gmail-mcp

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

Tools

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

Requirements

• Python 3.10+

License

MIT