Gmail MCP Server

io.github.mcp-z/mcp-gmailv2.3.1

Gmail integration with OAuth authentication, message search, batch operations, and Sheets export

Node.jsstdioremoteofficial registry

context tax

queued

security

queued

cold start

queued

freshness

Active27d ago

Install Gmail MCP server

claude mcp add io-github-mcp-z-mcp-gmail -e GOOGLE_CLIENT_ID='<google-client-id>' -e GOOGLE_CLIENT_SECRET='<google-client-secret>' -- npx -y @mcp-z/mcp-gmail

{
  "mcpServers": {
    "io-github-mcp-z-mcp-gmail": {
      "command": "npx",
      "args": [
        "-y",
        "@mcp-z/mcp-gmail"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "<google-client-id>",
        "GOOGLE_CLIENT_SECRET": "<google-client-secret>"
      }
    }
  }
}

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

{
  "mcpServers": {
    "io-github-mcp-z-mcp-gmail": {
      "command": "npx",
      "args": [
        "-y",
        "@mcp-z/mcp-gmail"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "<google-client-id>",
        "GOOGLE_CLIENT_SECRET": "<google-client-secret>"
      }
    }
  }
}

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

{
  "servers": {
    "io-github-mcp-z-mcp-gmail": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@mcp-z/mcp-gmail"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "<google-client-id>",
        "GOOGLE_CLIENT_SECRET": "<google-client-secret>"
      }
    }
  }
}

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

{
  "mcpServers": {
    "io-github-mcp-z-mcp-gmail": {
      "command": "npx",
      "args": [
        "-y",
        "@mcp-z/mcp-gmail"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "<google-client-id>",
        "GOOGLE_CLIENT_SECRET": "<google-client-secret>"
      }
    }
  }
}

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

Configuration

Variable	Required	Secret	Description
GOOGLE_CLIENT_ID	yes	—	Google OAuth client ID (required for OAuth authentication modes)
GOOGLE_CLIENT_SECRET	—	yes	Google OAuth client secret (optional for public clients)
GOOGLE_SERVICE_ACCOUNT_KEY_FILE	—	—	Path to service account JSON key file (required for service-account auth mode)
AUTH_MODE	—	—	Authentication mode
HEADLESS	—	—	Disable browser auto-open, return auth URL instead (true/false)
REDIRECT_URI	—	—	OAuth redirect URI (optional, default: ephemeral loopback)
RESOURCE_STORE_URI	—	—	Resource store URI for CSV export files (file://)
PORT	—	—	HTTP server port (overrides --port)
BASE_URL	—	—	Base URL for HTTP transport (used for OAuth/DCR endpoints and file links)
LOG_LEVEL	—	—	Logging level
DCR_MODE	—	—	Dynamic Client Registration mode
DCR_VERIFY_URL	—	—	External verification endpoint URL (required for external DCR mode)
DCR_STORE_URI	—	—	DCR client storage URI (for self-hosted DCR mode)

Freshness

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

Last commit (default branch)
no data · GitHub
Latest release
no data · GitHub
Package published
no data · npm/PyPI
Registry entry updated
2026-09-13 · 27d ago · official registry · v2.3.1

FAQ

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

Run: claude mcp add io-github-mcp-z-mcp-gmail -e GOOGLE_CLIENT_ID='<google-client-id>' -e GOOGLE_CLIENT_SECRET='<google-client-secret>' -- npx -y @mcp-z/mcp-gmail. For Cursor, VS Code, Claude Desktop and Windsurf, use the install tabs above.

›Does Gmail require an API key?

Yes. It expects GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, of which 1 is a secret.

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

Yes — it offers both a hosted endpoint and a local stdio package.

›Is Gmail in the official MCP registry?

Yes, as io.github.mcp-z/mcp-gmail.