gmail-mcp

MCP server for reading Gmail and creating drafts via AI assistants (Claude, OpenClaw, etc.).

Security model:

• 🔒 Read-only by default — no send capability, ever

• 📋 Drafts only — human must open Gmail and send manually

• 🔍 Query whitelist — only configured filter queries are allowed

• 👤 Optional recipient whitelist for drafts

• 🔑 API key authentication for HTTP/SSE mode

Tools

Related MCP server: Gmail MCP Server

Setup

1. Google Cloud credentials

1. Go to Google Cloud Console

2. Create a project → Enable Gmail API

3. Create OAuth2 credentials (Desktop app type)

4. Download as credentials.json and place in the project folder

2. Install

git clone https://github.com/mortenv/gmail-mcp
cd gmail-mcp
pip install -e .
# or with uv:
uv sync

3. Configure

cp config.example.yaml config.yaml

Edit config.yaml:

• Add your filter queries (Gmail search syntax)

• Optionally restrict draft recipients

4. Authenticate

First run opens a browser for OAuth2 login:

gmail-mcp config.yaml

Token is cached in token.json — subsequent runs don't need the browser.

5. Connect to Claude / OpenClaw

stdio mode (local):

{
  "mcpServers": {
    "gmail": {
      "command": "gmail-mcp",
      "args": ["/path/to/config.yaml"]
    }
  }
}

HTTP/SSE mode (remote server):

export GMAIL_MCP_API_KEY=$(python -c "import secrets; print(secrets.token_hex(32))")
gmail-mcp --http config.yaml

{
  "mcpServers": {
    "gmail": {
      "url": "https://your-server:8001/sse",
      "headers": { "X-API-Key": "your-key" }
    }
  }
}

Filter syntax

Uses standard Gmail search syntax:

filters:
  - query: "label:inbox"
    label: "Inbox"
  - query: "from:boss@company.com"
    label: "From boss"
  - query: "label:invoices newer_than:30d"
    label: "Recent invoices"

The AI can narrow results by appending terms to a base query: "label:inbox subject:urgent" — allowed if label:inbox is whitelisted.

Security notes

• credentials.json and token.json are gitignored — never commit them

• OAuth scopes: gmail.readonly + gmail.compose (no gmail.send)

• Drafts require human review — the server has no way to send email

License

MIT