Gmail MCP Server

by pulsemcpcom.pulsemcp/gmailv0.4.12

MCP server for Gmail with OAuth2 (personal) and service account (Workspace) support.

81Node.jsstdioofficial registry

context tax

queued

security

queued

cold start

queued

freshness

Maintained40d ago

Install Gmail MCP server

claude mcp add gmail-pulsemcp -e GMAIL_OAUTH_CLIENT_ID='<gmail-oauth-client-id>' -e GMAIL_OAUTH_CLIENT_SECRET='<gmail-oauth-client-secret>' -e GMAIL_OAUTH_REFRESH_TOKEN='<gmail-oauth-refresh-token>' -e GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY='<gmail-service-account-private-key>' -- npx -y gmail-workspace-mcp-server

{
  "mcpServers": {
    "gmail-pulsemcp": {
      "command": "npx",
      "args": [
        "-y",
        "gmail-workspace-mcp-server"
      ],
      "env": {
        "GMAIL_OAUTH_CLIENT_ID": "<gmail-oauth-client-id>",
        "GMAIL_OAUTH_CLIENT_SECRET": "<gmail-oauth-client-secret>",
        "GMAIL_OAUTH_REFRESH_TOKEN": "<gmail-oauth-refresh-token>",
        "GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<gmail-service-account-private-key>"
      }
    }
  }
}

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

{
  "mcpServers": {
    "gmail-pulsemcp": {
      "command": "npx",
      "args": [
        "-y",
        "gmail-workspace-mcp-server"
      ],
      "env": {
        "GMAIL_OAUTH_CLIENT_ID": "<gmail-oauth-client-id>",
        "GMAIL_OAUTH_CLIENT_SECRET": "<gmail-oauth-client-secret>",
        "GMAIL_OAUTH_REFRESH_TOKEN": "<gmail-oauth-refresh-token>",
        "GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<gmail-service-account-private-key>"
      }
    }
  }
}

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

{
  "servers": {
    "gmail-pulsemcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "gmail-workspace-mcp-server"
      ],
      "env": {
        "GMAIL_OAUTH_CLIENT_ID": "<gmail-oauth-client-id>",
        "GMAIL_OAUTH_CLIENT_SECRET": "<gmail-oauth-client-secret>",
        "GMAIL_OAUTH_REFRESH_TOKEN": "<gmail-oauth-refresh-token>",
        "GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<gmail-service-account-private-key>"
      }
    }
  }
}

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

{
  "mcpServers": {
    "gmail-pulsemcp": {
      "command": "npx",
      "args": [
        "-y",
        "gmail-workspace-mcp-server"
      ],
      "env": {
        "GMAIL_OAUTH_CLIENT_ID": "<gmail-oauth-client-id>",
        "GMAIL_OAUTH_CLIENT_SECRET": "<gmail-oauth-client-secret>",
        "GMAIL_OAUTH_REFRESH_TOKEN": "<gmail-oauth-refresh-token>",
        "GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "<gmail-service-account-private-key>"
      }
    }
  }
}

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

Configuration

Variable	Required	Secret	Description
GMAIL_OAUTH_CLIENT_ID	—	yes	OAuth2 client ID from Google Cloud Console (for personal Gmail accounts).
GMAIL_OAUTH_CLIENT_SECRET	—	yes	OAuth2 client secret from Google Cloud Console.
GMAIL_OAUTH_REFRESH_TOKEN	—	yes	Refresh token from the OAuth2 setup script.
GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL	—	—	Service account email address (for Google Workspace).
GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY	—	yes	Service account private key in PEM format (for Google Workspace).
GMAIL_IMPERSONATE_EMAIL	—	—	Email address to impersonate (required for service account mode).
GMAIL_ENABLED_TOOLGROUPS	—	—	Comma-separated list of tool groups to enable (readonly, readwrite, readwrite_external).

Freshness

Maintained — last maintenance signal 40d ago. The newest of the signals below sets the band.

Last commit (default branch)
2026-08-30 · 40d ago · GitHub
Latest release
2025-07-03 · 15mo ago · GitHub · monorepo-latest-placeholder@0.0.0
Package published
no data · npm/PyPI
Registry entry updated
2026-08-30 · 40d ago · official registry · v0.4.12

FAQ

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

Run: claude mcp add gmail-pulsemcp -e GMAIL_OAUTH_CLIENT_ID='<gmail-oauth-client-id>' -e GMAIL_OAUTH_CLIENT_SECRET='<gmail-oauth-client-secret>' -e GMAIL_OAUTH_REFRESH_TOKEN='<gmail-oauth-refresh-token>' -e GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY='<gmail-service-account-private-key>' -- npx -y gmail-workspace-mcp-server. For Cursor, VS Code, Claude Desktop and Windsurf, use the install tabs above.

›Does Gmail require an API key?

Yes. It expects GMAIL_OAUTH_CLIENT_ID, GMAIL_OAUTH_CLIENT_SECRET, GMAIL_OAUTH_REFRESH_TOKEN, GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY, of which 4 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 com.pulsemcp/gmail.