A Gmail MCP server lets Claude read and draft inside a person's existing Gmail through Google OAuth. Use it when the agent must act as that person. Switch to an agent inbox when each agent needs its own address, isolation, and send reputation, because a shared human mailbox does not scale to a fleet.
When you connect Claude to email, Gmail is the default most developers reach for first. The agent already runs in Claude Desktop or Claude Code, MCP connectors are familiar, and the mailbox is the one you already live in. That path works when Claude should search your threads, draft replies in your voice, and label mail the way you would.
It fails when you spin up a second agent, then a tenth. Shared human mailboxes mix agent traffic with personal mail. Quotas and daily send caps sit on the person, not on the agent. Reputation damage from one noisy bot can hit everything that leaves that address.
This guide walks through both Claude paths for Gmail MCP: Google's official remote server for Claude Desktop, and a local community server for Claude Code. It covers the OAuth scopes and tool surface, the quotas and plan gates that bite, why a shared mailbox breaks for a fleet, and when to switch to an agent-owned inbox instead.
What is a Gmail MCP server?
A Gmail MCP server is a Model Context Protocol server that exposes Gmail operations as tools Claude can discover and call. Model Context Protocol is an open standard for tool calling. The client is Claude Desktop, Claude Code, or another MCP host. The server talks to Gmail and returns typed verbs such as search threads, get a thread, create a draft, and apply labels.
The primitive is a person mailbox. Claude acts inside an existing human Gmail account after Google OAuth. It does not provision a new address for the agent. That is the whole model, and it is the right one when the job is "act as me in my Gmail." Google ships a remote Gmail MCP at https://gmailmcp.googleapis.com/mcp/v1. Community packages also run a local Gmail MCP on your machine for Claude Code. Both attach to a person's Gmail, and neither creates an agent-owned inbox.
What is the official remote setup path?
Google's remote Gmail MCP is the official path for Claude.ai and Claude Desktop. Status is Developer Preview through the Workspace Developer Preview Program. You need membership in that program, a Google Cloud project, and a Claude Enterprise, Pro, Max, or Team plan.
Enable the Gmail API and the Gmail MCP API in the project, then configure the OAuth consent screen with the Gmail MCP scopes. Create a Web application OAuth client whose authorized redirect URI is https://claude.ai/api/mcp/auth_callback. From the Cloud CLI that looks like gcloud services enable gmail.googleapis.com --project=PROJECT_ID followed by gcloud services enable gmailmcp.googleapis.com --project=PROJECT_ID.
In Claude, open Settings (or Admin settings), then Connectors, then Add custom connector. Set the server name to Gmail, set the remote MCP server URL to https://gmailmcp.googleapis.com/mcp/v1, and paste the OAuth client ID and client secret under Advanced settings. Complete Google sign-in. After auth, Claude can search threads, open a thread, create drafts, and manage labels in that Gmail account.
Official tools on the remote server are create_draft, get_thread, label_message, label_thread, list_drafts, list_labels, search_threads, unlabel_message, and unlabel_thread. There is no create_inbox and no send tool on this surface. Drafts land in Gmail for a human to review and send. Google also documents indirect prompt injection when MCP hosts read untrusted email content, so treat inbound mail as untrusted input and review actions Claude takes on your behalf before you send.
What is the local uvx package path?
Claude Code often needs a local Gmail MCP because Claude.ai connectors do not sync into the CLI. Community packages fill that gap. One example is pliablepixels/claude-gmail-mcp: a small uvx server with a Gmail API OAuth backend and an SMTP/IMAP app-password fallback.
Create a Google Cloud Desktop OAuth client, enable the Gmail API, then run the package auth helper against the downloaded credentials JSON with uvx --from claude-gmail-mcp claude-gmail-mcp-auth /path/to/credentials.json. Register the server with claude mcp add gmail --scope user -- uvx claude-gmail-mcp. The OAuth path requests the gmail.modify scope and stores a refresh token under ~/.config/claude-gmail-mcp/. If no token is present, the same package can fall back to SMTP and IMAP with a Gmail address and app password in the environment.
Local community servers are not the Google remote MCP. Tool names, scopes, and send behavior differ by package, so read the README for the package you install and treat it as one named example rather than a Google-supported product.
Which OAuth scopes does Gmail MCP need?
Official Google Gmail MCP scopes are gmail.readonly and gmail.compose. Readonly covers search, thread read, and label listing. Compose covers drafts. Together they match the remote tool surface without granting a broad modify or send grant on the official path.
Community local servers often request gmail.modify so the agent can send and alter messages through the Gmail API. That is a wider grant than the official remote pair. App-password SMTP and IMAP paths skip OAuth scopes and store a password-like secret instead. Pick the narrowest path that matches the job: draft-only review fits readonly plus compose, while autonomous send needs a community path that documents send plus a clear review policy.
Which limits matter for quotas, send caps, and plan gates?
Three layers of limits show up in practice: MCP and API quotas, Gmail daily send caps, and product gates on who can connect. Google's Gmail MCP quotas use query cost units. Per minute per project the ceiling is 1,200,000. Per minute per user per project it is 6,000.
On the MCP toolset table, create_draft costs 10, get_thread costs 40, and search_threads costs 10. The underlying Gmail API prices messages.send at 100 units and caps recipients at 500 per message. Those numbers live on Google's Gmail API quota reference.
Daily send caps sit on the mailbox, not on the MCP process. For personal Gmail, Google's help center describes a temporary block when you send to more than 500 recipients in one email or more than 500 emails in a day. Workspace paid accounts sit higher, commonly described around 2,000 messages per day per user, with lower figures for trial and mail merge. Treat the mailbox owner as the rate limit for agent traffic that shares that address.
Product gates matter before quotas do. Official Claude access needs Enterprise, Pro, Max, or Team. Official Google remote access needs Developer Preview membership and the Cloud project setup above. A Free Claude plan or a project outside the preview program will not complete the official connector path.
Why a shared Gmail mailbox fails for a fleet of agents
One human Gmail shared across many agents collapses identity, quota, and reputation into a single address. Every agent sends as the same person, so recipients cannot tell which bot wrote the mail, audit trails mix personal threads with agent automation, and labels and search become a shared workspace with no tenant boundary.
Quotas and daily caps are per user. Ten agents that each send a modest volume still hit the same 500 or roughly 2,000 message ceiling, and one runaway loop throttles everyone on that mailbox. Reputation is shared too: a spam complaint or bounce spike from one agent hurts deliverability for the human owner and for every other agent on the address, with no clean way to isolate a noisy bot without cutting off the mailbox.
When should you use an agent inbox instead of Gmail MCP?
Use Gmail MCP when Claude must act as a specific person inside an existing Gmail: triage that person's mail, draft replies in their voice, or label threads they already own. Use an agent inbox when each agent needs its own address, its own message store, and isolation from other agents and from personal mail.
The decision is the primitive, not the brand. Person-mailbox MCP maps Google OAuth onto mail you already have. Agent-inbox MCP provisions an address the agent owns, then exposes create, send, reply, and thread tools against that inbox. The email MCP servers compared post maps those primitives across vendors. The AgentMail vs Gmail API post covers the same split at the API layer.
If you are wiring Claude Code, Cursor, or Codex to an inbox API rather than to Gmail, How to use MCP with an email API is the install walkthrough. Broader MCP picks live in Best MCP servers for AI agents. Cluster links for MCP and agent tooling sit under Build.
How do I install AgentMail MCP in Claude for create_inbox?
AgentMail hosts an MCP server at https://mcp.agentmail.to/mcp with create_inbox among 36 tools. OAuth sessions also get organization selection tools. That is the agent-inbox path: the agent provisions an address, then sends and replies from it, without OAuth into a human Gmail.
For Claude Desktop and Claude.ai, open Settings, then Connectors, then Add custom connector with the name AgentMail and URL https://mcp.agentmail.to/mcp. The connector fields look like this:
{
"name": "AgentMail",
"url": "https://mcp.agentmail.to/mcp"
}For Claude Code, add the hosted HTTP transport, then complete OAuth on first use. Connectors installed on Claude.ai do not sync to Claude Code, so install the server in the CLI separately:
# add the hosted AgentMail MCP server over HTTP
claude mcp add --transport http agentmail https://mcp.agentmail.to/mcpAsk the agent to create an inbox, send a message, list threads, and reply when mail arrives. That loop is the fleet-friendly model: one address per agent, no shared human mailbox.
What AgentMail does not do
AgentMail does not OAuth into a person's Gmail or IMAP mailbox. If the job is act as me inside my existing Gmail, Gmail MCP or another person-mailbox bridge is the fit. AgentMail MCP also does not expose pods, custom-domain create or verify, or webhook CRUD; those stay on the REST API and SDKs.
Gmail MCP fits Claude when the agent must work inside a person's Gmail. An agent inbox fits when each agent needs its own address and isolation. Pick the primitive that matches the job, then install the matching MCP server.
AgentMail is the first email provider built for AI agents. Create an inbox in one API call, send and receive email, no OAuth and no domain verification. Free tier, no credit card required.
