Gmail MCP: How to Connect Gmail to Claude and AI Agents

A Gmail MCP server hands your mailbox to an AI agent as a set of standardized tools. It's a Model Context Protocol server, which means a model like Claude can search threads, read a conversation, manage labels, and draft (or in some implementations send) email through natural language instead of bespoke API code. People mean two different things when they say "Gmail MCP." One is Google's official remote Gmail MCP server, currently in developer preview. The other is a family of community Gmail MCP servers you self-host, the most popular being GongRzhe/Gmail-MCP-Server. This guide walks through what each one does, how to connect a Gmail MCP server to Claude step by step, the tools they expose, and the security trade-offs you'll want to understand before pointing an LLM at your inbox.

What is the Gmail MCP server?

MCP is an open standard from Anthropic for connecting AI assistants to external systems, data, and tools. A Gmail MCP server implements that standard for Gmail. It advertises a list of callable tools (search, read, draft, label, and so on) to any MCP-compatible client, and the client's model decides when to invoke them. The goal is simple. Replace one-off, per-app API integrations with a single, uniform way for agents to read and act on email under your own permissions.

In practice "Gmail MCP" splits into two camps with meaningfully different capabilities and trust models.

Official Google Gmail MCP server

Google now publishes a remote, Google-hosted Gmail MCP server at https://gmailmcp.googleapis.com/mcp/v1. It's documented in the Gmail API guides and is one of several official Google Workspace MCP servers (Gmail, Drive, Calendar, Chat, and People). It's labeled Developer Preview, available through the Google Workspace Developer Preview Program, and the configuration guide was last updated June 5, 2026.

The official server is deliberately conservative, and that matters. It uses only two OAuth scopes, gmail.readonly and gmail.compose, which means it can read, search, label, and create drafts, but cannot send or permanently delete email. That draft-not-send posture is an intentional safety guardrail.

Community Gmail MCP servers

Community servers run locally (or on your own infrastructure) and typically request broader Gmail access for fuller coverage. The most prominent is GongRzhe/Gmail-MCP-Server ("Gmail AutoAuth"), a Node server for Claude Desktop with automatic OAuth2 setup. Unlike the official server, it can send email, with attachments, HTML, and multipart bodies, plus manage filters, run batch operations, and download attachments. One caveat. The repository was archived (made read-only) on March 3, 2026, though it remains usable. Other community options include shinzo-labs/gmail-mcp (full Gmail API coverage) and broader suites like taylorwilsdon/googleworkspacemcp.

Gmail MCP tools and capabilities

The two camps expose very different tool surfaces.

Official Google server tools

The official reference lists these tools:

• search_threads, get_thread: find and read conversations
• list_labels, create_label: inspect and create labels
• label_thread, unlabel_thread, label_message, unlabel_message: organize mail
• create_draft, list_drafts: compose drafts (but not send)

Google frames the capabilities as "Read data: Search emails, retrieve threads, and list labels" and "Take action: Create draft emails and label messages."

GongRzhe community server tools

The community server is much broader, roughly 18 tools. That includes send_email, draft_email, read_email, download_attachment, search_emails (with Gmail operators), modify_email, delete_email (permanent), full label CRUD (list_email_labels, create_label, update_label, delete_label, get_or_create_label), batch_modify_emails, batch_delete_emails, and filter management (create_filter, list_filters, get_filter, delete_filter, create_filter_from_template).

Can the Gmail MCP server send email?

This is the single most important distinction. The official Google server cannot send, only draft and label. Community servers like GongRzhe's can send, including replies and attachments. Pick based on whether you actually want an agent that can put mail in motion on its own.

How to set up the official remote Gmail MCP server with Claude

Connecting the official server takes a Google Cloud project, the gcloud CLI, and a supported MCP client. Per Google's docs, supported clients are Google Antigravity and Claude, and Claude support requires an Enterprise, Pro, Max, or Team plan.

1. Enable the required APIs

gcloud services enable gmail.googleapis.com --project=PROJECT_ID
gcloud services enable gmailmcp.googleapis.com --project=PROJECT_ID

2. Configure the OAuth consent screen and scopes

In the Google Cloud console under Google Auth Platform > Branding, set an app name (e.g. "Gmail MCP Server"), a user support email, the audience (Internal if you have a Workspace org; otherwise External, which requires adding test users), and a contact email, then accept the Google API Services User Data Policy. Manually add the two scopes:

https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.compose

3. Create a Web-application OAuth client

Create an OAuth 2.0 client ID and secret with Application type = Web application. The authorized redirect URI depends on your client:

• Claude: https://claude.ai/api/mcp/auth_callback
• Antigravity: https://antigravity.google/oauth-callback

4. Add the connector in Claude

In Claude.ai or Claude Desktop, go to Settings > Connectors > Add custom connector. Set the server name to Gmail, the remote MCP server URL to https://gmailmcp.googleapis.com/mcp/v1, and under Advanced settings enter your OAuth client ID and secret.

4 (alt). Connect via Google Antigravity

Edit ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "gmail": {
      "serverUrl": "https://gmailmcp.googleapis.com/mcp/v1",
      "oauth": {
        "clientId": "OAUTH_CLIENT_ID",
        "clientSecret": "OAUTH_CLIENT_SECRET"
      }
    }
  }
}

How to set up the GongRzhe community server (Claude Desktop, local)

Need send, attachments, or filters? The local route is the popular choice.

1. Create OAuth credentials in Google Cloud

Create or select a Google Cloud project, enable the Gmail API, then go to APIs & Services > Credentials > Create Credentials > OAuth client ID and choose Desktop app (a Desktop client needs no redirect URI; a Web client uses http://localhost:3000/oauth2callback). Download the client JSON, rename it gcp-oauth.keys.json, and place it globally:

mkdir -p ~/.gmail-mcp && mv gcp-oauth.keys.json ~/.gmail-mcp/

2. Install and authenticate

Install via Smithery or run the one-time auth step, which launches a browser for OAuth and writes ~/.gmail-mcp/credentials.json:

# Smithery install
npx -y @smithery/cli install @gongrzhe/server-gmail-autoauth-mcp --client claude

# Or run the one-time auth flow directly
npx @gongrzhe/server-gmail-autoauth-mcp auth

3. Add it to your Claude Desktop config

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["@gongrzhe/server-gmail-autoauth-mcp"]
    }
  }
}

A Docker image is also available. It reads GMAIL_OAUTH_PATH and GMAIL_CREDENTIALS_PATH environment variables and mounts an mcp-gmail volume for persisted credentials.

Example tool calls

Once you're connected, you talk to it in natural language and the model maps your requests to tools. Common patterns reported across implementations:

• "Show my last 5 unread emails" → search_threads / search_emails with Gmail filters
• "Summarize this thread and draft a reply" → get_thread then create_draft / draft_email
• "Label everything from billing@ as Finance" → search_threads + label_thread / create_label
• "Extract the action items and dates from this conversation" → get_thread, with the model parsing content

Choosing your route: official vs community

| | Official Google server | GongRzhe community server | |---|---|---| | Hosting | Remote, Google-managed | Self-hosted (local / Docker) | | Send email | No (draft only) | Yes | | Scopes | readonly + compose | Broad Gmail access | | Tools | ~10 (read, draft, label) | ~18 (send, delete, filters, batch) | | Clients | Antigravity, Claude (paid plans) | Claude Desktop | | Cost | Free, plan-gated | Free, open source | | Maintenance | Active (dev preview) | Archived read-only (Mar 2026) |

Go with the official server when you want a clean OAuth boundary, least-privilege scopes, and don't need autonomous sending. Reach for a community server when you need full Gmail coverage and you're comfortable running it yourself with broader permissions.

Is the Gmail MCP server safe?

Pointing an LLM at an inbox opens up a real, documented attack surface. Treat it seriously.

Prompt injection

Google's own docs explicitly warn about indirect prompt injection. Because MCP clients have access to powerful tools through the Gmail MCP server, a malicious email can hide instructions (white-on-white text, tiny fonts) that the model reads and obeys. This isn't theoretical. Security researchers at Radware demonstrated ShadowLeak, a zero-click flaw that exfiltrated Gmail data via ChatGPT's Deep Research agent (disclosed June 2025, patched by OpenAI in early August 2025). And Aim Labs, the research arm of Aim Security, disclosed EchoLeak (CVE-2025-32711) in Microsoft 365 Copilot, where a single crafted email could leak inbox data with no user interaction.

Least privilege and token risk

The official server's readonly + compose scopes are a deliberate least-privilege design. Community servers that request send/delete scopes carry materially higher risk. There's a separate issue too. MCP servers hold persistent OAuth tokens that can outlive a password change, and the connector itself is part of your trust boundary. Again, not hypothetical: in September 2025, researchers at Snyk documented a backdoored npm MCP server, postmark-mcp, whose send_email tool was modified to silently BCC every outgoing email to an attacker-controlled domain. It was the first publicly tracked supply-chain compromise of a real-world MCP server.

Practical guardrails

Google's guidance is concrete. Only connect trusted applications, avoid processing email from unverified or untrusted sources, and carefully review all AI-initiated actions before they execute. For production, one more hardening step is common practice: run agents under a separate, scoped service identity rather than your own personal account.

From manual email to event-driven agents

That last point hints at where this is heading. Connecting your personal Gmail to Claude Desktop is one thing. Running Gmail as a tool inside a production agent is another. This is the model behind gamut.so (built by Datawizz): an AI agent knowledge workforce where agents use MCP servers like the Gmail MCP server as tools, triggered by events and acting through APIs under their own least-privilege identity, not a human running a full-scope OAuth session on a laptop. The shift is from "connect my inbox to a chatbot" to "an agent acts on email on a trigger, with scoped permissions and an audit trail."

FAQ

Is there an official Google Gmail MCP server? Yes. It's a remote, Google-hosted server at https://gmailmcp.googleapis.com/mcp/v1, currently in developer preview.

Can the Gmail MCP server send emails? The official Google server can't. It only drafts and labels. Community servers like GongRzhe's can send.

How do I connect Gmail MCP to Claude? Either add the official remote server as a custom connector (requires a paid Claude plan and a Google Cloud OAuth client), or add a local community server to claude_desktop_config.json via npx.

Which OAuth scopes does the official server need? https://www.googleapis.com/auth/gmail.readonly and https://www.googleapis.com/auth/gmail.compose.

Is it free? What plan do I need? The servers are free. The official one is gated to Claude Enterprise, Pro, Max, or Team plans (and Google Antigravity).

Is the Gmail MCP server safe? It carries real prompt-injection and token-aggregation risk. Use least-privilege scopes, only connect trusted sources, review AI actions, and consider a separate agent identity for anything automated.

Always re-verify commands, scopes, and redirect URIs against the live docs. The official server is newly launched and community package details are version-specific.