Gmail MCP Server

by a1-x-techio.github.A1-x-Tech/mcp-google-gmailv1.0.0

MCP server for the Gmail API: search, read and send email, manage drafts, labels and the trash.

0Node.jsstdioofficial registry

context tax

queued

security

queued

cold start

queued

freshness

Active5d ago

Install Gmail MCP server

claude mcp add google-gmail -e GOOGLE_GMAIL_CLIENT_SECRET='<google-gmail-client-secret>' -e GOOGLE_GMAIL_REFRESH_TOKEN='<google-gmail-refresh-token>' -e GOOGLE_GMAIL_ACCESS_TOKEN='<google-gmail-access-token>' -- npx -y mcp-google-gmail

{
  "mcpServers": {
    "google-gmail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-google-gmail"
      ],
      "env": {
        "GOOGLE_GMAIL_CLIENT_SECRET": "<google-gmail-client-secret>",
        "GOOGLE_GMAIL_REFRESH_TOKEN": "<google-gmail-refresh-token>",
        "GOOGLE_GMAIL_ACCESS_TOKEN": "<google-gmail-access-token>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).

{
  "mcpServers": {
    "google-gmail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-google-gmail"
      ],
      "env": {
        "GOOGLE_GMAIL_CLIENT_SECRET": "<google-gmail-client-secret>",
        "GOOGLE_GMAIL_REFRESH_TOKEN": "<google-gmail-refresh-token>",
        "GOOGLE_GMAIL_ACCESS_TOKEN": "<google-gmail-access-token>"
      }
    }
  }
}

Settings → Developer → Edit Config (claude_desktop_config.json), then restart.

{
  "servers": {
    "google-gmail": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-google-gmail"
      ],
      "env": {
        "GOOGLE_GMAIL_CLIENT_SECRET": "<google-gmail-client-secret>",
        "GOOGLE_GMAIL_REFRESH_TOKEN": "<google-gmail-refresh-token>",
        "GOOGLE_GMAIL_ACCESS_TOKEN": "<google-gmail-access-token>"
      }
    }
  }
}

Add to .vscode/mcp.json in your workspace.

{
  "mcpServers": {
    "google-gmail": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-google-gmail"
      ],
      "env": {
        "GOOGLE_GMAIL_CLIENT_SECRET": "<google-gmail-client-secret>",
        "GOOGLE_GMAIL_REFRESH_TOKEN": "<google-gmail-refresh-token>",
        "GOOGLE_GMAIL_ACCESS_TOKEN": "<google-gmail-access-token>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json.

Configuration

Variable	Required	Secret	Description
GOOGLE_GMAIL_CLIENT_ID	—	—	Google OAuth2 client id (refresh-token flow).
GOOGLE_GMAIL_CLIENT_SECRET	—	yes	Google OAuth2 client secret (refresh-token flow). Treat it as a secret.
GOOGLE_GMAIL_REFRESH_TOKEN	—	yes	Google OAuth2 refresh token, exchanged for access tokens automatically. Treat it as a secret.
GOOGLE_GMAIL_ACCESS_TOKEN	—	yes	Static OAuth2 access token (~1h lifetime) — alternative to the refresh-token trio, mostly for testing.
GOOGLE_GMAIL_OAUTH_PORT	—	—	Fixed port for the loopback listener of the in-chat login (127.0.0.1 + PKCE). Set it when the client runs over SSH port forwarding; otherwise a free port is picked per login.
GOOGLE_GMAIL_API_BASE	—	—	API root override.
GOOGLE_GMAIL_TIMEOUT_MS	—	—	Per-request timeout in milliseconds.
GOOGLE_GMAIL_MAX_RETRIES	—	—	Retries on transient errors (429 always; 5xx/network for reads).

Freshness

Active — last maintenance signal 5d ago. The newest of the signals below sets the band.

Last commit (default branch)
2026-10-04 · 5d ago · GitHub
Latest release
2026-09-23 · 16d ago · GitHub · v1.0.0
Package published
no data · npm/PyPI
Registry entry updated
2026-09-23 · 16d ago · official registry · v1.0.0

FAQ

›How do I install the Gmail MCP server in Claude Code?

Run: claude mcp add google-gmail -e GOOGLE_GMAIL_CLIENT_SECRET='<google-gmail-client-secret>' -e GOOGLE_GMAIL_REFRESH_TOKEN='<google-gmail-refresh-token>' -e GOOGLE_GMAIL_ACCESS_TOKEN='<google-gmail-access-token>' -- npx -y mcp-google-gmail. For Cursor, VS Code, Claude Desktop and Windsurf, use the install tabs above.

›Does Gmail require an API key?

Yes. It expects GOOGLE_GMAIL_CLIENT_SECRET, GOOGLE_GMAIL_REFRESH_TOKEN, GOOGLE_GMAIL_ACCESS_TOKEN, of which 3 are secrets.

›Can I use Gmail as a remote (hosted) MCP server?

No hosted endpoint is published; it runs locally over stdio.

›Is Gmail in the official MCP registry?

Yes, as io.github.A1-x-Tech/mcp-google-gmail.