A Gmail MCP server gives an AI client tools to search your inbox, read threads, draft replies and manage labels — so you can ask Claude to triage email or summarise a thread in natural language. There are two clean routes: Google's official remote connector or a community npx server. Here's the setup.
Option A — Google's official Workspace connector (recommended)
The first-party path uses OAuth and a remote endpoint, so no local process runs.
- In Google Cloud Console, enable the Gmail API for your project (APIs & Services → Library).
- Create an OAuth client ID (Web application) and add the redirect URI
https://claude.ai/api/mcp/auth_callback. Copy the client ID and secret. - In Claude Desktop or claude.ai → Settings → Connectors → Add custom connector, point it at Google's remote Gmail MCP URL, and complete the OAuth login.
Connecting a custom remote connector from Claude requires a Pro/Max/Team/Enterprise plan. This route keeps tokens with Google and never exposes a password to the model.
Option B — community npx server (local)
If you want a local stdio server, @gongrzhe/server-gmail-autoauth-mcp is the most common. Authenticate once, then drop it in:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": ["-y", "@gongrzhe/server-gmail-autoauth-mcp"]
}
}
}
Claude Code one-liner:
claude mcp add --transport stdio gmail -- npx -y @gongrzhe/server-gmail-autoauth-mcp
It opens a browser the first time to grant Gmail scopes, then caches the token locally. Restart the client; see MCP config file location.
Verify
Ask: "Search my inbox for unread emails from this week and summarise the top 5." Real threads back confirms it works.
Common problems
invalid_grant/ auth loop — the OAuth consent screen or redirect URI is misconfigured; re-check the exact callback URL.- No tools in client — Node 18+ for
npx; see Cursor MCP not working. - Read but can't send — you granted read-only scopes; re-authorise with
gmail.send/gmail.modify.
Security
Email is among the most sensitive scopes you can grant an AI. Prefer read-only (gmail.readonly) unless you genuinely need send/modify, review the consent screen carefully, and never paste long-lived tokens into shared configs. See MCP security best practices and our take on MCP permission scoping.
Going further
Gmail pairs naturally with calendar and drive for a full assistant stack — see the Gmail agent profile, Google Calendar MCP setup and Google Drive MCP setup. Browse the communication category or pick a ready loadout.