Configure the Gmail MCP server

Gmail offers a remote Model Context Protocol (MCP) server that allows AI agents to securely interact with Gmail data. By configuring the Gmail MCP server, you enable AI applications like Gemini CLI, Claude, or IDEs to perform actions in Gmail.

The Gmail MCP server provides a standardized way for AI agents to:

Read data: Search emails, retrieve threads, and list labels.
Take action: Create draft emails and label messages.
Respect security: Inherit the same permissions and data governance controls as the user.

Prerequisites

A Google Cloud project. To create a project, see Create a project.
An MCP client, like Gemini CLI.
To run the commands on this page, set up the gcloud CLI in a local development environment by following these steps:
1. Install the Google Cloud CLI. If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. If you're using an external identity provider (IdP), sign in to the gcloud CLI with your federated identity. For more information, see Sign in to the gcloud CLI with your federated identity.
3. Initialize the gcloud CLI.

Configure the Gmail MCP server

To use the Gmail MCP server, you must enable it in your Google Cloud project and then configure your MCP client to connect to it.

Enable the APIs

To use the Gmail MCP server, you must enable the following API in your Google Cloud project:

Gmail API

CLI

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

Replace PROJECT_ID with your Google Cloud project ID.

Console

Enable the APIs in the Google Cloud console:

Enable the APIs

Enable the MCP services

To enable the MCP components for Gmail, you must enable the following service in your Google Cloud project:

Gmail MCP API

CLI

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

Replace PROJECT_ID with your Google Cloud project ID.

Console

Enable the MCP services in the Google Cloud console:

Enable the MCP services

The Gmail MCP server uses OAuth 2.0 for authentication and authorization. You must configure the OAuth consent screen before you can create an OAuth client ID.

In the Google Cloud console, go to Google Auth Platform > Branding.

Go to Branding
If you have already configured the Google Auth Platform, you can configure the following OAuth Consent Screen settings in Branding, Audience, and Data Access. If you see a message that says Google Auth Platform not configured yet, click Get Started:
1. Under App Information, in App name, type Gmail MCP Server.
2. In User support email, select your email address or an appropriate Google group.
3. Click Next.
4. Under Audience, select Internal. If you can't select Internal, select External.
5. Click Next.
6. Under Contact Information, enter an Email address where you can be notified about any changes to your project.
7. Click Next.
8. Under Finish, review the Google API Services User Data Policy and if you agree, select I agree to the Google API Services: User Data Policy.
9. Click Continue.
10. Click Create.
11. If you selected External for user type, add test users:
  1. Click Audience.
  2. Under Test users, click Add users.
  3. Enter your email address and any other authorized test users, then click Save.
Click Data Access > Add or Remove Scopes. A panel appears with a list of scopes for each API that you've enabled in your Google Cloud project.
1. Under Manually add scopes, paste the scopes for the Gmail MCP server:
  - https://www.googleapis.com/auth/gmail.readonly
  - https://www.googleapis.com/auth/gmail.compose
2. Click Add to Table.
3. Click Update.
4. After selecting the scopes required by your app, on the Data Access page, click Save.

Configure your MCP client

To add the Gmail remote MCP server to your MCP client, follow the instructions for your client.

Gemini CLI

To add the Gmail remote MCP server to your Gemini CLI, add the server configuration to your settings.json file.

Create an OAuth 2.0 client ID and secret:
1. In the Google Cloud console, go to Google Auth Platform > Clients > Create Client
  
  Go to Create Client
2. Select Desktop app as the application type.
3. Enter a Name.
4. Click Create and copy your Client ID and Client Secret.
Open or create the configuration file ~/.gemini/settings.json.

Add the mcpServers configuration to settings.json:

{
  "mcpServers": {
    "gmail": {
      "httpUrl": "https://gmailmcp.googleapis.com/mcp/v1",
      "oauth": {
        "enabled": true,
        "clientId": "OAUTH_CLIENT_ID",
        "clientSecret": "OAUTH_CLIENT_SECRET",
        "scopes": [
          "https://www.googleapis.com/auth/gmail.readonly",
          "https://www.googleapis.com/auth/gmail.compose"
        ]
      }
    }
  }
}

Replace the following:

OAUTH_CLIENT_ID: The client ID you created.
OAUTH_CLIENT_SECRET: The client secret you created.

Save settings.json.
Start Gemini CLI:
```
gemini
```
In Gemini CLI, authenticate with the MCP server by running the following command:
```
/mcp auth gmail
```
1. When prompted, press 1 to open an authentication page in your browser. If you're working over SSH, follow the instructions in the CLI.
2. Sign in to your Google Account.
3. Review the requested OAuth scopes and click Allow.
4. A message appears confirming authentication was successful.

In Gemini CLI, run /mcp list to view your configured MCP servers and their tools.

The response is similar to the following:

🟢 gmail - Ready (10 tools)
  Tools:
  - create_draft
  - create_label
  - get_thread
  - label_message
  - label_thread
  - list_drafts
  - list_labels
  - search_threads
  - unlabel_message
  - unlabel_thread

The remote MCP server is ready to use in Gemini CLI.

Claude

To use the Gmail remote MCP server with Claude.ai or Claude Desktop, you must have the Claude Enterprise, Pro, Max, or Team plan.

To add the Gmail remote MCP server to Claude, configure a custom connector with an OAuth client ID and secret.

Create an OAuth 2.0 client ID and secret:
1. In the Google Cloud console, go to Google Auth Platform > Clients > Create Client
  
  Go to Create Client
2. Select Web application as the application type.
3. Enter a Name.
4. In the Authorized redirect URIs section, click + Add URI, and then add https://claude.ai/api/mcp/auth_callback in the URIs field.
5. Click Create and copy your Client ID and Client Secret.
Configure the MCP server in Claude:
1. In Claude.ai or Claude Desktop, go to Settings (or Admin settings) > Connectors.
2. Click Add custom connector.
3. Enter the connection details for the Gmail product:
  - Server name: Gmail.
  - Remote MCP server URL: https://gmailmcp.googleapis.com/mcp/v1
4. In Advanced settings, enter your OAuth client ID and OAuth client secret.
5. Click Add.

Others

Many AI applications have ways to connect to a remote MCP server. You typically need to enter details about the server, like its name, endpoints, transport protocol, and authentication method. For the Gmail remote MCP server, enter the following:

Server name: gmail
Server URL: https://gmailmcp.googleapis.com/mcp/v1
Transport: HTTP
Authentication: The Gmail remote MCP server uses OAuth 2.0. For details, see Learn about authentication and authorization.

For more details on connecting different types of clients, see Configure MCP in an AI application.

Test the Gmail MCP server

After you configure the MCP client, you can verify the connection by running some test prompts.

Try asking your MCP client the following questions:

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

The client filters for emails from Ariel using gmail.search_threads, retrieves the latest thread's content with gmail.get_thread, and then summarizes it for you.
"Draft an email to ariel@example.com saying that I approve the marketing plan."

The client uses gmail.create_draft to create an email in your drafts folder, allowing you to review and send it from Gmail.

If the tools execute successfully and you receive relevant responses, your Gmail MCP server is correctly configured.

Troubleshooting

If you encounter issues connecting to the MCP server, you can check for errors in the OAuth logs. Ask your administrator to check the OAuth log events in the security investigation tool.

Tool reference

The following tools are available for the Gmail MCP server:

create_draft
get_thread
label_message
label_thread
list_drafts
list_labels
search_threads
unlabel_message
unlabel_thread

Important security consideration: Indirect prompt injection

When you expose a language model to untrusted data, there is a risk of an indirect prompt injection attack. Because MCP clients like Gemini CLI have access to powerful tools and APIs through the Gmail MCP server, they can read, modify, and delete data in your Google Account.

To mitigate these risks, follow these best practices:

Only use trusted tools. Never connect Gmail MCP server to untrusted or unverified applications.
Be cautious with untrusted inputs. Avoid asking your MCP client to process emails or other resources from unverified sources. These inputs may contain hidden instructions that can hijack your session, allowing an attacker to modify, steal, or delete your data.
Review all actions. Always carefully review the actions taken by your AI client on your behalf to ensure they are correct and align with your intentions.

Configure the Gmail MCP server Stay organized with collections Save and categorize content based on your preferences.

Prerequisites

Configure the Gmail MCP server

Enable the APIs

CLI

Console

Enable the MCP services

CLI

Console

Set up the OAuth consent screen

Configure your MCP client

Gemini CLI

Claude

Others

Test the Gmail MCP server

Troubleshooting

Tool reference

Important security consideration: Indirect prompt injection

Related section

Configure the Gmail MCP server