To connect Claude to Gmail via MCP, use Google's official remote Gmail MCP server at https://gmailmcp.googleapis.com/mcp/v1, or Anthropic's own Gmail connector inside Claude. Google's server is in Developer Preview, uses Streamable HTTP and signs each user in with OAuth 2.0, so the agent acts as that user. It can search, read, label, trash and draft mail, but it cannot send. Sending, sync and push notifications stay on the Gmail API.
A product whose agent works in many customers' inboxes needs per-user OAuth, token storage and an audit trail, the problem behind most MCP integrations. For the general difference, see MCP vs API.
Google's Gmail MCP server is a remote server that Google hosts at https://gmailmcp.googleapis.com/mcp/v1. It is one of the Google Workspace MCP servers: Drive, Docs, Sheets, Slides, Calendar, Chat, People and Classroom each have their own. Google opened the Workspace MCP server to public developer preview on May 1, 2026, and the setup guide lists membership in the Google Workspace Developer Preview Program as a prerequisite.
Setup happens in a Google Cloud project you own. You enable the Gmail API (gmail.googleapis.com) and the Gmail MCP API (gmailmcp.googleapis.com), configure the OAuth consent screen with the gmail.readonly and gmail.compose scopes, and create an OAuth client of type Web application with Use this client for an AI-powered agent selected. Google's troubleshooting checks that setting first.
Google's tool reference documents search, thread and message reads, drafts and labels. The server's own tools/list response, which answers without sign-in, returned 23 tools in October 2026, adding get_draft, trash_thread, trash_message and spam tools. None of them sends mail. Read tools/list from your client for the current list.
The Gmail REST API at gmail.googleapis.com/gmail/v1 exposes the full mailbox: messages, drafts, threads, labels, history, attachments, and settings such as filters, forwarding, send-as aliases, vacation responders and delegates. It also offers users.watch for push notifications through Cloud Pub/Sub.
It accepts OAuth 2.0 tokens from a user's consent, or from a service account with domain-wide delegation in a Workspace organization.
Every client below needs the Google Cloud project, consent screen and an OAuth client. Google does not support dynamic client registration, so each client needs your client ID and secret, and Google requires an exact match on the redirect URI you register.
Google's server goes in as a custom connector. On Team and Enterprise plans, an Owner adds it under Organization settings > Connectors, and members then connect to it.
Claude also has its own Gmail connector, under Customize > Connectors, where each user signs in with Google. It can send, reply and forward, and by default asks for approval before each of those actions. Google's server is the better fit when your organization wants its own OAuth client and scopes in its own Google Cloud project.
Register http://localhost:8080/callback as a redirect URI on a Web application client. Then add the server with the two Gmail scopes pinned, using the pre-configured credentials options:
Claude Code prompts for the secret and keeps it out of your config. Run /mcp, select gmail and sign in. The server's metadata advertises wider scopes, including gmail.modify, gmail.send and https://mail.google.com/, and oauth.scopes makes Claude Code request only the two that Google's setup lists.
If you have connected Anthropic's Gmail connector on claude.ai, it appears in Claude Code automatically when you sign in with a claude.ai subscription. For sign-in loops, scope errors and 401s in the CLI, see Claude Code MCP OAuth.
Register http://localhost:8787/callback for the desktop app and, if people sign in from the web or Cursor Agents, https://www.cursor.com/agents/mcp/oauth/callback. Then add the server to ~/.cursor/mcp.json or a project's .cursor/mcp.json with static OAuth credentials, read from environment variables:
Codex takes a pre-registered client. Google matches the redirect URI exactly, port included, so first give Codex a fixed callback in ~/.codex/config.toml:
Register that URL on your Web application client, then add the server and sign in:
Check that codex mcp add prints the callback URL you registered. Codex stores the secret in config.toml, so keep it private. Codex prefers the scopes a server advertises, and Gmail's list includes https://mail.google.com/, so read the consent screen before you approve.
Google's guide also covers Antigravity, through ~/.gemini/config/mcp_config.json. Any other client needs the server URL, Streamable HTTP as the transport, and OAuth 2.0 with your client.
The MCP server reads, organizes and drafts. The API owns everything that sends mail or runs without a person in the loop.
In Google's own example, the client uses create_draft to put a message in the user's Drafts folder so they can review and send it from Gmail. An agent that must send a follow-up or an autonomous reply needs users.messages.send or users.drafts.send on the REST API. For an interactive assistant that is a sensible default, since a person sees every message first.
Each user signs in through a browser and grants the scopes, and the agent inherits what that user can see and do. Google's setup covers one sign-in model: user OAuth through a client you create.
Access tokens last about an hour, so a client needs a refresh token, which Google issues only for requests with access_type=offline. After the first consent, a process holding that refresh token can keep working without the user present, so a headless job such as a scheduled digest needs one interactive sign-in per user first. What MCP does not give you is a way to act for users who never signed in.
The authorization code flow is per-user consent, the same identity model as MCP. A service account with domain-wide delegation lets a Google Workspace administrator authorize one client to act as users in the organization without prompts. It does not apply to consumer @gmail.com accounts, and because it reaches every user's data, Google recommends reviewing those service accounts regularly.
gmail.readonly and gmail.compose are restricted scopes whichever path requests them. A public app that requests them needs restricted-scope verification, and an app that accesses the data from or through a third-party server also needs a security assessment by a Google-approved assessor under the CASA framework, repeated at least every 12 months. Apps used only inside your own Workspace organization with an Internal consent screen are exempt, and Google's setup guide has you pick Internal when you can.
The MCP server is preview software, so its tools can change. The API has no LLM-ready tool schemas: you build requests, parse MIME messages, handle pagination and map errors yourself. The MCP server returns tool definitions with input and output schemas and read-only hints a client can use directly, which is faster for an interactive assistant.
Gmail API usage limits for projects created on or after May 1, 2026 are 1,200,000 quota units per minute per project and 6,000 per minute per user per project. Usage under 80,000,000 units per day per project is not billed. messages.send and drafts.send cost 100 units each, against 5 for messages.list, and a message can have at most 500 recipients. The MCP server has its own quota, counted in query cost: 1,200,000 per minute per project and 6,000 per minute per user per project, with get_thread at 40 and search_threads at 10. Google applies the same tiering model to Workspace APIs and the MCP servers.
Google hosts the server and maintains the tool schemas. You own the Google Cloud project, OAuth client, scopes and verification, plus token storage if your software holds the tokens. Indirect prompt injection is the main risk: Google warns that untrusted email can carry hidden instructions and requires you to screen prompts and responses, with its Model Armor service or your own documented solution.
You own requests, MIME handling, retries, pagination, the token lifecycle and push infrastructure. A users.watch registration must be renewed at least every 7 days, and Google recommends once a day. Each watched user gets at most one notification per second; Google drops the rest.
Whether the token comes from the MCP OAuth flow or a direct API grant, it has to live somewhere: encrypted at rest, isolated per tenant, and revocable when a user disconnects. Google refresh tokens stop working when the user revokes access, changes their password, or leaves the token unused for six months. Google also allows 100 refresh tokens per Google Account per OAuth client ID, and a new one beyond that silently invalidates the oldest.
In a multi-tenant agent, fifty customers mean fifty OAuth grants, fifty refresh lifecycles and fifty revocation paths, and a tool call must never pick up the wrong one. Per-user OAuth for MCP integrations covers this design and its failure modes.
AgentKit is an MCP gateway that runs each user's OAuth flow, stores their tokens encrypted with AES-256-GCM under a key per environment, refreshes them and calls tools as that user. Its Gmail connector lists 48 tools: 21 read, 19 write and 8 destructive, including gmail_send_message, gmail_send_draft, gmail_list_history and gmail_watch_mailbox. It uses your own Google OAuth app: paste the Gmail connection's redirect URI into a Web application client in Google Cloud, then enter the client ID, secret and scopes on the connection. The consent screen shows your app.
You create a Virtual MCP server once per agent role, and all users share its URL. Before each run, your back end mints a session token for one user. Scalekit checks the token, finds that user's Gmail account and calls Gmail with it, so your agent never receives a Gmail token.
Once per agent role: create the server.
Before each run: check the user's account, then mint a token. If the account is not active, send the user the authorization link.
During the run: connect any MCP client with the server URL and the session token as a bearer header. With the Python MCP SDK (version 2):
How session tokens behave:
The server also lists a connect_account tool. If the user's Gmail account is not connected, a tool call tells the agent to call it for an authorization link. To revoke one user, delete their connected account; other users keep working:
AgentKit keeps tool call logs for 90 days with the tool name, connected account, identifier, status and duration. They never contain a tool's successful response, so message content stays out of them.
For an interactive agent that searches, reads, labels and drafts for human review, Google's Gmail MCP server is the faster route, though it is preview software and cannot send. For an agent that sends mail, syncs, reacts to inbound events or acts for users who never signed in, build on the REST API. Many production Gmail agents use both. The per-user credential work is the same either way.
Yes. Google hosts a remote Gmail MCP server at https://gmailmcp.googleapis.com/mcp/v1, one of the Google Workspace MCP servers, in Developer Preview. Each user signs in with OAuth 2.0 and the agent acts with that user's permissions.
In Claude.ai or Claude Desktop, connect Anthropic's Gmail connector under Customize > Connectors, or add Google's server as a custom connector with your own OAuth client. In Claude Code, add Google's server with your client ID, secret and a fixed callback port, then sign in from /mcp.
No. create_draft leaves the message in the user's Drafts folder to review and send from Gmail. An agent that sends on its own needs users.messages.send or users.drafts.send on the REST API, or a connector that wraps them.
Google lists no charge for standard use today. Gmail API usage under 80,000,000 quota units per day per project is not billed, and Google says it will give at least 90 days' notice before billing changes take effect.
Tool calls without a valid access token get a 401, and Google access tokens last about an hour. If you sign in every hour, your client is not getting a refresh token, which Google issues only for requests with access_type=offline. If you are signed out after a week, your External app is in Testing status, where refresh tokens expire after 7 days.
No. Its gmail.readonly and gmail.compose scopes are restricted scopes, the same ones the REST API uses. A public app needs restricted-scope verification, and apps used only inside your own Workspace organization are exempt.
AgentKit runs each user's OAuth flow against your Google OAuth app, stores and refreshes the tokens, and calls Gmail as that user. Your agent connects to one Virtual MCP server URL with a short-lived session token bound to one user, so it never receives a Gmail token.
Details checked October 2026.
