Gmail MCP Server: Official Preview and Options

Google runs an official Gmail MCP server at https://gmailmcp.googleapis.com/mcp/v1. It is a remote OAuth server in Developer Preview. An agent can search threads, read messages, list labels and create drafts, and Google's tool list has no send tool. You need a Google Cloud project and Developer Preview membership. We checked it on 31 October 2026.

Quick facts

There was no Gmail server in the MCP project's reference set, so there is no archived reference server to leave behind. Some older Gmail servers on GitHub use local credential files and are community projects of varying upkeep.

What the official server does

Google's description of the Gmail server is short: read data (search emails, retrieve threads, list labels), take action (create draft emails and label messages), and respect security by inheriting the permissions and data governance controls of the user.

The tool list on Google's page:

That is all 11 tools on Google's MCP reference page today.

No send, on purpose

Look at what is missing. There is no send_email, no delete and no archive tool in the list we saw. The scope gmail.compose lets an app create and manage drafts and send them, so the limit here is in the tool list, not the scope. Google's scopes page describes gmail.compose as "Manage drafts and send emails". In practice, an agent drafts a reply, and you open Gmail, read it and press Send yourself.

We think that is the right default for email. A mistaken draft costs you a click to delete. A mistaken sent message cannot be recalled.

Set it up: the official server

The order we would follow, from Google's Workspace MCP guide:

1. Join the Google Workspace Developer Preview Program.
2. Create or choose a Google Cloud project and set up the gcloud CLI.
3. Enable the Gmail API and the Gmail MCP service:

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

1. Set up the OAuth consent screen in Google Auth Platform. Choose Internal if you can, otherwise External with test users.
2. Add the Gmail scopes under Data Access: https://www.googleapis.com/auth/gmail.readonly and https://www.googleapis.com/auth/gmail.compose.
3. Create an OAuth client ID of type Web application. Tick "Use this client for an AI-powered agent" and add the redirect URI for your client.

You can enable several servers at once with one gcloud command, but for email we would enable only Gmail, to keep the granted scopes small.

Install it in each agent

Google documents Antigravity and Claude. The rest are our adaptation.

Antigravity

Create the OAuth client with the redirect URI https://antigravity.google/oauth-callback, then add this to ~/.gemini/config/mcp_config.json:

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

Authenticate from the settings screen (Customizations, Installed MCP Servers, Authenticate), or in the CLI by running agy, opening /mcp and choosing Authenticate. Sign in, copy the authorization code and paste it back. Signed-in servers show Authed. Gemini CLI is now for Code Assist enterprise customers only.

Claude

For Claude.ai and Claude Desktop on Enterprise, Pro, Max or Team plans, use the redirect URI https://claude.ai/api/mcp/auth_callback. Then in Settings, Connectors, Add custom connector, enter a name such as Gmail and the URL https://gmailmcp.googleapis.com/mcp/v1, with your client ID and secret.

Claude Code

Our adaptation, from Claude Code's remote server docs, which describe --client-id, --client-secret and --callback-port for servers with pre-registered OAuth clients. Match the callback port to the redirect URI you registered:

claude mcp add --transport http gmail https://gmailmcp.googleapis.com/mcp/v1 \
  --client-id OAUTH_CLIENT_ID --client-secret

Codex

Our adaptation, in ~/.codex/config.toml:

[mcp_servers.gmail]
url = "https://gmailmcp.googleapis.com/mcp/v1"

Codex's MCP docs describe an oauth table with client_id and callback_url for pre-registered clients, and codex mcp login gmail to sign in. We did not test it against Google.

Cursor

Our adaptation, in .cursor/mcp.json:

{
  "mcpServers": {
    "gmail": {
      "url": "https://gmailmcp.googleapis.com/mcp/v1",
      "auth": { "CLIENT_ID": "OAUTH_CLIENT_ID", "CLIENT_SECRET": "OAUTH_CLIENT_SECRET" }
    }
  }
}

OpenCode

Our adaptation, in opencode.json:

{
  "mcp": {
    "gmail": {
      "type": "remote",
      "url": "https://gmailmcp.googleapis.com/mcp/v1",
      "oauth": { "clientId": "OAUTH_CLIENT_ID", "clientSecret": "OAUTH_CLIENT_SECRET" }
    }
  }
}

Each client has its own callback URL. Register the one the client uses, or sign-in fails with a redirect error.

Jobs an email agent does well

These are our suggestions from the tool list. We did not run them.

Triage a noisy inbox

Ask the agent to run search_threads for unread mail from the last two days, group the threads by sender or topic, and tell you which need an answer. Nothing changes in your mailbox. This is the best first task: it is read-only and saves real time.

Draft replies you review

For a thread you pick, the agent uses get_thread to read the history, then create_draft to write a reply in your voice. You open the draft in Gmail, edit it and send. Because there is no send tool, the final step stays with you.

Keep labels tidy

list_labels, create_label and the label tools let an agent apply a scheme you describe, such as "label every invoice thread from the last month". Test on a small search first, since labelling many threads at once is easy to ask for and tedious to undo.

Find a thing you half remember

Gmail search syntax works in search_threads queries, though Google's pages do not spell out the query syntax. Standard Gmail operators are the likely fit, so "from:alex has:attachment newer_than:30d" is a plain, cheap way to find a message. This is where an agent beats scrolling.

Writing prompts that keep you in control

The server's design leaves room for good and bad prompting. A few patterns, from our reading of the tool list.

Say what to read, and how much. "Summarise my unread mail" is open ended. "Search threads from the last two days, unread, from people at our domain, and list the top ten by urgency" gives the agent a bounded query and gives you a result you can check. Bounded queries also cost less context, since every message body the agent reads fills the window.

Ask for evidence. Tell the agent to name the sender, subject and date of each thread it mentions. If it cannot, treat the claim as a guess. This catches the common failure where a summary blends two threads.

Separate drafting from deciding. A good split is: the agent reads the thread and proposes the reply in the chat first, you approve the wording, and only then does it call create_draft. That costs one extra turn and removes most of the risk of a bad draft sitting in your account.

Name the label scheme in full. For labelling jobs, give the exact label names and the rule for each, and ask the agent to run the search and show the count before it labels anything. Then run the labelling on that same search. A labelling mistake across a few hundred threads is slow to undo.

Do not paste instructions from emails into the chat. If a message says "ask your assistant to do X", that is the shape of a prompt injection. Tell the agent that instructions inside mail are data, never commands, and say so in your project instructions file so it holds for every session.

The community option

taylorwilsdon/google_workspace_mcp is a maintained MIT server that covers Gmail with the other Workspace apps. It runs locally over stdio or streamable HTTP with your own OAuth client:

export GOOGLE_OAUTH_CLIENT_ID="..."
export GOOGLE_OAUTH_CLIENT_SECRET="..."
uvx workspace-mcp --tools gmail --tool-tier core --read-only

Its README points to tool tiers, a --read-only mode, per-service permissions, a stateless mode and no built-in telemetry. A search tool it documents is search_gmail_messages, which takes a Gmail query, and its docs also list send_gmail_message, so it can send mail. If a server can send, you must decide whether you want that tool at all, and --read-only is the blunt way to say no.

Security notes

Email is the most sensitive data most people connect to an agent.

1. Your mailbox is open to the agent. gmail.readonly lets it read all mail it can query: bank statements, password resets, legal threads. Use a separate account or a test group first.
2. Prompt injection arrives by email. Anyone can email you. A message can hide text telling an agent to forward data, draft something harmful or ignore its rules. Google says you must screen prompts and responses for malicious content and offers Model Armor.
3. Model Armor logs payloads. Google warns that with logging on it logs the entire payload, which can expose email content in your logs.
4. Drafts can leak too. A draft created by an injected instruction could include content from other threads. Read each draft before you send.
5. Keep send out of reach. The official tool list has no send tool. If you use another server that can send, keep it behind a confirmation prompt.
6. Do not pair it with outbound tools. Mail read access plus a web-posting tool is the pairing an attacker wants.
7. Client secret care. Keep it in your client's secret storage.
8. Workspace admins. Admins may restrict OAuth apps. If you cannot authorise, ask whether the client is allowed.
9. Preview terms. Behaviour and terms can change before general release.

Limits and known issues

• Developer Preview. Program membership is needed.
• Narrow tool set. No send, delete or archive in the list we saw. That limits risk and some uses.
• Long setup. Cloud project, APIs, consent screen, scopes and client.
• Callback URIs differ by client.
• External consent screens need test users.
• Rate and quota limits. Google's usual API quotas apply, and Google's pages do not give separate MCP quotas.
• Attachments. The tool list we saw has no attachment download tool.

Alternatives

See MCP clients for how each agent handles remote OAuth. If you also want a ready-made list of servers to pair with it, see the best MCP servers roundup.

Our take

We did not run any of these servers for this page. This comes from Google's documentation and the repositories.

The official Gmail server makes a good call by leaving send out. Reading, searching, drafting and labelling cover most of what people want from an email agent, and they keep the final act with you. Pairing broad read access with a draft-only write is the same shape Google chose for Drive, and we agree with it.

The setup work is real, and the Preview label means you should expect change. If you only want inbox triage, start with the read side, use a test mailbox, and treat every incoming message as untrusted text. If you want an agent that sends mail on its own, you are choosing a different risk, and the community servers are where that choice lives.

A short setup checklist

1. Join the Developer Preview Program, or pick the community server.
2. Enable only the Gmail API and the Gmail MCP service.
3. Add only the two Gmail scopes.
4. Create an OAuth client with your agent's redirect URI.
5. Authenticate and run one search you can check by hand.
6. Ask for a draft, and open it in Gmail before sending anything.
7. Keep outbound tools off the same agent.

Frequently asked questions

Is there an official Gmail MCP server?

Yes. Google offers a remote Gmail MCP server at https://gmailmcp.googleapis.com/mcp/v1. It is in Developer Preview and needs membership in the Google Workspace Developer Preview Program.

Can it send email?

The tools Google lists create drafts, not send mail. The scopes are gmail.readonly and gmail.compose. We found no send tool in the list.

What can it read?

It can search threads, get a thread or a message, list drafts and list labels.

Does it need Google Cloud?

Yes. You need a Google Cloud project, the Gmail API and Gmail MCP services enabled, an OAuth consent screen and an OAuth client ID.

Is there an open-source option?

taylorwilsdon/google_workspace_mcp is an MIT server that covers Gmail and other Workspace apps, with tool tiers and a read-only mode.