Gmail Blade MCP

Production Gmail MCP server for AI agents. Token-efficient, write-safe, thread-intelligent.

Features

What makes this different

• Token-efficient by default — HTML→plaintext stripping, body truncation, quoted-reply deduplication, concise list format
• Write-safe — GMAIL_WRITE_ENABLED=true env gate + confirm=true on destructive operations
• Thread-intelligent — thread_mode=deduped strips quoted replies; latest shows only newest message
• Incremental sync — gmail_state + gmail_changes via Gmail history.list API
• Rate-limit aware — automatic exponential backoff on 429 errors
• Gemini AI — classify and summarise emails using Google Gemini (optional, requires GOOGLE_API_KEY)
• Credential-safe — OAuth tokens scrubbed from error messages

Quick Start

1. Install

uv sync

2. Set up Gmail API credentials

1. Go to Google Cloud Console
2. Create a project (or select existing)
3. Enable the Gmail API
4. Create OAuth 2.0 credentials (Desktop application)
5. On the OAuth consent screen, set publishing status to "In production" — in "Testing" status Google expires refresh tokens after 7 days, which breaks any long-running server. (The "unverified app" warning at consent is a one-time click-through; if you have a Google Workspace org, marking the app Internal avoids the warning entirely.)
6. Download the JSON file and save as ~/.gmail-blade/credentials.json (or pass --client-id/--client-secret to the auth verb instead)

3. Authenticate

uv run gmail-blade-mcp auth            # mints modify+send scopes (default)
uv run gmail-blade-mcp auth --scopes read   # read-only grant

A browser window opens for OAuth consent. After authorising, the verb prints a paste-ready credential block:

GMAIL_OAUTH_CLIENT_ID=...
GMAIL_OAUTH_CLIENT_SECRET=...
GMAIL_OAUTH_REFRESH_TOKEN=...

and (unless --no-save-token) also saves the refresh token to ~/.gmail-blade/token.json (mode 0600) for standalone use.

The server itself never opens a browser. If no credentials are available it returns a typed error telling you to run gmail-blade-mcp auth. Verify current credentials any time with:

uv run gmail-blade-mcp auth --check    # prints account email + granted scopes

Stallari / headless deployments: set the three GMAIL_OAUTH_* env vars (e.g. paste them into Stallari → Connections → gmail-blade-mcp). When GMAIL_OAUTH_REFRESH_TOKEN is set the server builds credentials in memory and never touches ~/.gmail-blade/. Note the scope grant is fixed when the token is minted — to enable write tools later you need both GMAIL_WRITE_ENABLED=true and a token minted with --scopes write.

4. Configure MCP client

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "gmail-blade": {
      "command": "uv",
      "args": ["--directory", "/path/to/gmail-blade-mcp", "run", "gmail-blade-mcp"],
      "env": {
        "GMAIL_WRITE_ENABLED": "false"
      }
    }
  }
}

Environment Variables

Security

• Write operations disabled by default — set GMAIL_WRITE_ENABLED=true to enable
• Permanent delete requires confirm=true — use gmail_move to TRASH for soft delete
• OAuth tokens never appear in error messages — regex scrubbing on all error paths
• The server can never open a browser — interactive consent exists only in the auth CLI verb; headless deployments get typed errors, not hangs
• token.json written 0600 — and in env-credential mode nothing is written to disk at all
• Bearer auth uses constant-time comparison — secrets.compare_digest()
• Credentials stored locally — ~/.gmail-blade/, never transmitted

Development

make install-dev    # Install with dev + test deps
make test           # Unit tests (no Gmail needed)
make check          # Lint + format + type check
make test-cov       # Tests with coverage

email-v1 Contract

This server implements the Sidereal email-v1 domain contract — the same tool semantics as fastmail-blade-mcp. Skills targeting email-v1 work with either provider.

License

MIT