How to Connect Gmail to an MCP Server

Direct answer: Google provides an official remote Gmail MCP server at https://gmailmcp.googleapis.com/mcp/v1. To connect it, enable both the Gmail API and Gmail MCP API in a Google Cloud project, configure Google OAuth consent and the required scopes, create OAuth client credentials for your MCP host, then add the server using Streamable HTTP and OAuth 2.0.

Google currently marks this service as part of the Workspace Developer Preview Program. Client screens, OAuth requirements, and preview availability can change, so check Google’s current setup documentation before deploying it.

What the Gmail MCP server can do

The Google-hosted server exposes Gmail operations to an MCP-capable AI application. Its published tools are:

Tool	Purpose
`search_threads`	Find Gmail threads using a Gmail search query.
`get_thread`	Retrieve a complete conversation thread.
`get_message`	Retrieve an individual message.
`list_labels`	List labels available in the mailbox.
`label_message`	Add a label to one message.
`label_thread`	Add a label to a thread.
`unlabel_message`	Remove a label from one message.
`unlabel_thread`	Remove a label from a thread.
`list_drafts`	List existing Gmail drafts.
`create_draft`	Create a draft for review in Gmail.

The published tool list does not include a send-email tool. Treat draft creation and sending as separate actions, and review drafts before sending them manually.

Prerequisites

A Google Cloud project.
The Google Cloud CLI installed, updated, authenticated, and initialized if you plan to use command-line setup.
An MCP-capable host that supports remote Streamable HTTP connections and OAuth 2.0.
Permission to configure APIs and OAuth in the Google Cloud project.
A Gmail account that your OAuth configuration allows to authorize the connection.

Step 1: Enable the Gmail services

Enable both services in the same Google Cloud project. The Gmail API alone is not sufficient for the hosted MCP endpoint.

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

Replace YOUR_PROJECT_ID with the project that will own the OAuth configuration. If the command fails, confirm that the project exists, billing or organization policy requirements are satisfied where applicable, and your account has permission to enable services.

Open Google Auth Platform for the project.
Complete the Branding settings, including the application name and support details requested by Google.
Choose an Audience. Google’s sample setup uses Internal where that option is available. Otherwise choose External.
For an External app, add the Gmail accounts that will test the integration as authorized test users.
Open Data Access and add the scopes required by Google’s Gmail MCP setup.

Required Gmail OAuth scopes

Google’s documented setup requests these scopes:

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

gmail.readonly permits reading Gmail data. gmail.compose permits creating drafts. Explain these permissions to users before they authorize the connection. Google classifies Gmail scopes by access and sensitivity; restricted scopes can trigger OAuth verification, and storing or transmitting restricted-scope data on a server can require a security assessment. Review Google’s current scope and verification policy for your application.

Step 3: Create an OAuth client

Create the OAuth client type required by your MCP host. The redirect URI and client type vary by host, so use the host’s current instructions when registering the callback.

In Google Auth Platform, open Clients.
Create an OAuth client.
Select the application type requested by your MCP host.
Record the client ID and client secret securely.
Register the exact redirect or callback URI supplied by the host. OAuth redirect URIs must match exactly, including scheme, hostname, path, and trailing slash.

Do not paste a client secret into a public repository, browser bundle, issue, prompt, or shared configuration file. Use the host’s secret-management facility or an environment variable.

Step 4: Add Gmail to an MCP client

Use these generic connection parameters when your MCP client lets you enter a remote server manually:

Setting	Value
Server name	`gmail`
URL	`https://gmailmcp.googleapis.com/mcp/v1`
Transport	Streamable HTTP
Authentication	OAuth 2.0

Enter the OAuth client ID and secret where the client requests them, save the connection, and complete Google’s authorization screen. Recheck the target client’s documentation for exact field names and callback requirements.

Claude with Gmail MCP

Google documents a Claude-specific path for supported Claude.ai or Claude Desktop plans: Enterprise, Pro, Max, or Team.

Create the Google OAuth client as described above.
In Claude, add a custom connector.
Set the connector URL to https://gmailmcp.googleapis.com/mcp/v1.
Provide the Google OAuth client ID and client secret.
Complete the OAuth flow in the browser.
Approve the requested Gmail scopes and return to Claude.

If Claude reports a redirect mismatch, compare the callback URI in Google Auth Platform with the URI shown by Claude’s connector screen character by character.

Other MCP clients

For Cursor, desktop agents, internal assistants, and other MCP hosts, use the generic URL and transport above only if the client supports remote Streamable HTTP and OAuth callbacks. Some clients support only local process servers or require a different configuration format. The client determines how credentials are stored and how the browser authorization flow starts.

Step 5: Verify the connection safely

Start with read-only prompts that identify a narrow result:

What did Ariel say in her last email about our marketing plan?

Then verify draft creation with a clearly bounded request:

Draft an email to ariel@example.com saying that I approve the marketing plan. Do not send it.

Open Gmail and confirm that the draft exists and contains the expected recipient and text. The documented Gmail MCP tool set supports creating a draft, but does not list a send operation.

OAuth and administrator controls

Workspace administrators can review third-party applications and the OAuth scopes they request. Administrators may classify apps as Trusted, Limited, or Blocked and restrict access to Google services. A policy can prevent users from authorizing an app that requests restricted services unless the app is trusted.

If users cannot authorize the connector, ask the Workspace administrator to check the application’s status, requested scopes, and organizational unit policies. Google Workspace OAuth logs can help identify rejected or incomplete authorization attempts.

Security: treat email as untrusted input

Email is user-generated content and can contain indirect prompt injection. A malicious message may instruct an AI client to reveal data, modify labels, create unwanted drafts, or perform another action. Google’s guidance says to use trusted applications, treat untrusted email inputs cautiously, screen prompts and responses, and review the client’s actions.

Use a trusted, verified MCP client and keep it updated.
Start with read-only searches and narrow prompts.
Require explicit review before labeling, drafting, or other mailbox changes.
Never follow instructions found inside an email unless they are independently verified.
Keep OAuth client secrets out of source control and logs.
Grant only the scopes required by the workflow.
Use Workspace administrator controls to restrict unapproved applications.

Google’s official setup guidance states: “Never connect Gmail MCP server to untrusted or unverified applications.”

Troubleshooting

Error or symptom	Likely cause	Fix
Service not found or API disabled	One of the two Google services is disabled in the project.	Enable both `gmail.googleapis.com` and `gmailmcp.googleapis.com`, then retry.
`redirect_uri_mismatch`	The callback URI registered in Google does not exactly match the MCP client’s URI.	Copy the URI from the client and register it exactly, including path and trailing slash.
`access_denied`	The user is not an authorized test user, an administrator blocked the app, or consent was denied.	For External apps, add the account as a test user; otherwise ask the Workspace administrator to review policy controls.
Insufficient scope	The OAuth grant omitted one of the documented Gmail scopes.	Request `gmail.readonly` and `gmail.compose`, then reauthorize and confirm the new consent.
Client cannot connect	The host does not support remote Streamable HTTP or OAuth callbacks.	Check the client’s MCP transport support and use its documented remote-server configuration.
Search returns no messages	The Gmail query is too narrow, the account is wrong, or the message is outside the accessible mailbox.	Try a simple query such as `from:ariel@example.com`, verify the signed-in account, and inspect the resulting thread IDs.
Draft is created but not sent	The published tool set includes draft creation but no send tool.	Open Gmail, review the draft, and send it manually if appropriate.
Authorization succeeds but tools fail	The OAuth token belongs to a different project or the client saved stale credentials.	Confirm the project, revoke the old grant if necessary, reconnect, and inspect the MCP client logs.

Performance, reliability, and cost considerations

Performance

Search for a narrow time range, sender, label, or subject before retrieving full threads.
Retrieve only the message or thread needed for the task.
Ask the model to summarize after retrieval rather than repeatedly fetching the same conversation.
Keep prompts explicit about the mailbox, sender, date range, and desired action.

Reliability

The service is in Developer Preview, so endpoint behavior and setup steps may change.
Keep a manual Gmail workflow available for urgent or consequential actions.
Log authorization failures and tool errors without storing message bodies or OAuth secrets unnecessarily.
Review actions in Gmail after any label or draft operation.

Cost

The documented setup requires a Google Cloud project, but the supplied Google instructions do not establish a per-message or per-tool price. Check current Google Cloud and Workspace terms for your account and region. Your MCP host may also have its own subscription or model charges.

Or skip the browser setup

If your goal is to capture a clean image or PDF of Gmail MCP documentation, setup screens, or an authenticated internal page, ScreenshotNeo provides a website screenshot API and MCP server. It accepts one GET request and returns PNG, JPEG, WebP, or PDF. Cookie and consent banners are accepted before capture, and more than 60 known consent platforms, newsletter popups, and chat widgets are removed. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed.

See the ScreenshotNeo API documentation for all options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://developers.google.com -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://developers.google.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://developers.google.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo also has an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. Only clean shots are billed, and each response identifies the result with X-Page-Verdict and X-Billed headers. You get 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

What URL do I use for the Gmail MCP server?

Use https://gmailmcp.googleapis.com/mcp/v1.

Which Gmail OAuth scopes do I need?

Google’s documented setup requests https://www.googleapis.com/auth/gmail.readonly and https://www.googleapis.com/auth/gmail.compose.

Can Gmail MCP send email?

The published tool list includes draft creation but no send-email tool. Create a draft, review it in Gmail, and send it manually.

Does this work with every MCP client?

It requires a client that supports remote Streamable HTTP and OAuth 2.0 callbacks. Check the client’s current MCP documentation.

Is the Gmail MCP service stable?

Google marks it as Developer Preview. Verify current availability and setup requirements before relying on it in production.

Connection checklist

Google Cloud project selected.
Gmail API enabled.
Gmail MCP API enabled.
OAuth Branding and Audience configured.
External test users added when required.
gmail.readonly and gmail.compose granted.
OAuth client callback URI matches the MCP host exactly.
MCP server URL and Streamable HTTP transport configured.
Read-only search tested.
Draft creation tested without sending.
Workspace administrator policy reviewed.
Untrusted email content treated as potentially malicious.