How to Set Up a Gmail MCP Server for Email Automation

Two coding agents pointed at the same inbox will happily overwrite each other's changes, or draft conflicting replies, and neither will notice. The limitation is not the intelligence of the model, but the lack of a shared workspace where agents and humans collaborate under a single view. In standard setups, email agents operate as isolated local processes. A developer configures an agent locally, running script tasks that pull emails and draft responses. When other team members or remote agents need to inspect the drafts or coordinate on replies, they have no direct visibility.

This isolation leads to several operational failures. If a customer service agent and a lead generation agent access the same mailbox without coordination, they will read the same unread messages, process them simultaneously, and draft double replies. Storing credentials such as Google Cloud client secrets and refresh tokens locally across multiple developer machines also increases the credential attack surface.

To resolve these barriers, teams must transition from local process execution to network-accessible services. The Model Context Protocol provides a structured way to connect clients and servers, translating API functions into standard tools. A Gmail MCP server is an implementation of the Model Context Protocol that translates Gmail API functions into tools for searching, reading, and composing emails. By exposing these capabilities as tools, any compliant client can search messages, retrieve threads, and manage drafts. However, to prevent these agents from operating in silos, teams must connect them to a shared workspace like Fastio. A shared workspace acts as the central coordination layer where all draft versions, attachments, and activity logs are kept in a single, searchable environment.

• Open WebUI MCP Setup: Adding Model Context Protocol Tools to Self-Hosted AIOpen WebUI supports the Model Context Protocol natively through Streamable HTTP connections, allowing self-hosted...
• Zed MCP Setup: Configuring Context Servers in the Zed EditorConfiguring a zed mcp environment connects the Zed editor AI assistant to local and remote context servers for codebase...
• FastAPI MCP: Exposing APIs as MCP Servers for AI Agent TeamsBuilding a FastAPI MCP server enables engineering teams to turn Python endpoints into Model Context Protocol tools for...
• Choosing a Filesystem MCP Server Alternative for Shared Agent WorkspacesAlthough Gartner predicts that 15% of day-to-day work decisions will be made autonomously through agentic AI by 2028,...
• How to Set Up the GitLab MCP Server for AI Devops AgentsSetting up a GitLab MCP server connects your AI coding assistants directly to your repositories, issues, and pipelines....
• How to Set Up an MCP Server for n8n Workflow AutomationThe Model Context Protocol turns n8n into an AI-accessible automation platform. This guide walks through setting up n8n...

More on this subject: MCP and Model Context Protocol (232 guides)

Setting up a Gmail MCP server requires establishing authentication with the Google APIs. Competitors often gloss over these steps, leaving developers stuck on authorization errors. To configure the server, you must create a project in the Google Cloud Console, enable the Gmail API, configure the OAuth Consent Screen, and generate the OAuth 2.0 client credentials.

The following list outlines the exact steps to generate your OAuth client credentials:

1. Log in to the Google Cloud Console and navigate to the project selector.
2. Click New Project, enter a descriptive name like Gmail-MCP-Server, and click Create.
3. Navigate to APIs & Services, then click Library. Search for Gmail API, click the result, and click Enable.
4. Go to APIs & Services, then click OAuth consent screen.
5. Select External if you are using a personal Gmail account (or select Internal if you are configuring this within a Google Workspace organization) and click Create.
6. Enter the required information, including the App name, User support email, and Developer contact information, then click Save and Continue.
7. Click Add or Remove Scopes. Search for and select the necessary Gmail scopes. For read-only access, select https://www.googleapis.com/auth/gmail.readonly. For composing and editing drafts, select https://www.googleapis.com/auth/gmail.compose. Click Update and then Save and Continue.
8. Under the Test users tab, click Add Users. Enter the email address of the Google account you want to connect to your MCP server and click Save.
9. Navigate to APIs & Services, then click Credentials. Click + Create Credentials at the top of the page and select OAuth client ID.
10. Under Application type, select Desktop application. Name the client Gmail MCP Client and click Create.
11. A dialog will display your Client ID and Client Secret. Click Download JSON to save these credentials to a file named credentials.json on your local machine.

By downloading the client credentials, you obtain the client ID and client secret needed to authorize your local or remote MCP server. Keep this JSON file secure and do not commit it to public version control repositories.

Once you have generated your client ID and client secret, you can configure the Gmail MCP server. For local testing and development with clients like Claude Desktop, you can run a community-maintained server that connects your local client to the Gmail API. A popular choice is the @gongrzhe/server-gmail-autoauth-mcp package, which automates the initial OAuth flow and manages refresh tokens.

To connect the server to Claude Desktop, you must modify your local configuration file. On macOS, this file is located at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, the path is %APPDATA%\Claude\claude_desktop_config.json.

You must edit the file to add a new server entry under the mcpServers key, providing your Google Cloud OAuth credentials as environment variables:

{
  "mcpServers": {
    "gmail-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@gongrzhe/server-gmail-autoauth-mcp"
      ],
      "env": {
        "GMAIL_CLIENT_ID": "your-client-id-here.apps.googleusercontent.com",
        "GMAIL_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

When Claude Desktop starts, it spawns the Gmail MCP server process. On the first launch, the server will open a browser window, prompting you to log in to the Google account you added as a test user. Once you log in and grant the requested permissions, the server generates a refresh token and saves it in a local configuration directory, typically ~/.gmail-mcp/token.json.

Subsequent starts will use this stored token, allowing the agent to read and compose emails headlessly. If you are running the client on Windows, you may need to wrap the npx command inside a shell runner to avoid path resolution errors. Ensure that the token file is kept secure, as it grants direct access to your Gmail account.

The Gmail API enforces strict security boundaries by categorizing its OAuth scopes. Scopes like https://mail.google.com/ provide full access to read, compose, send, and permanently delete email. Because of this level of access, Google classifies it as a restricted scope. Other scopes, such as https://www.googleapis.com/auth/gmail.readonly (for reading messages) and https://www.googleapis.com/auth/gmail.compose (for creating drafts), are classified as sensitive scopes.

Google Cloud Platform marks any application requesting sensitive or restricted scopes as an unverified app until it completes a formal review process. During development and personal testing, you can bypass these verification requirements entirely. By keeping your Google Cloud project in the Testing publishing status and adding your own email addresses to the Test users list, you can authorize the application without submitting it to Google. When you run the OAuth flow, a warning page will state that the app is unverified. You can bypass this screen by clicking Advanced and then clicking the link to proceed.

However, if you plan to distribute the email automation app to other users outside your Google Workspace organization, you must submit your project for OAuth verification. This process requires creating a public privacy policy, recording a video demonstrating how your app uses the scopes, and undergoing a security audit. For restricted scopes, Google requires an annual third-party security assessment, which can be costly and time-consuming. Developers should adhere to the principle of least privilege, selecting the narrowest scopes possible to limit security exposure.

Coordinate email automation in a shared workspace

Set up a shared workspace where your Gmail automation agents and human team edit drafts, organize attachments, and collaborate with full version history and semantic search. Starts with a 14-day free trial.

Start 14-Day Trial

While a local Gmail MCP server allows an AI agent to read and compose emails, running email automation directly from an agent's terminal introduces operational risk. If an agent drafts a reply and sends it immediately without human oversight, a misunderstanding or a hallucination can reach a client. To avoid this, teams use Fastio workspaces and coordination rooms as a shared substrate.

Instead of sending emails directly, the agent writes the email text and any parsed attachments into a shared Fastio workspace. Fastio offers Room Storage Mode, which creates an independent space where multiple agents and humans collaborate. The email agent reads incoming messages via the Gmail MCP server, parses the attachments, and writes them to a specific folder in the workspace. It then creates a draft reply as a Collaborative Note.

Collaborative Notes support real-time co-editing for both people and agents. An agent running Cursor or Claude Code can inspect the note, perform code checks or look up facts, and refine the draft. A human colleague can open the note in their browser, edit the text, and leave comments anchored to specific paragraphs.

Once the human approves the draft, the email agent retrieves the note content and uses the Gmail MCP server to send the message. This coordination pattern prevents independent agents from overwriting each other's work and keeps the entire history of email drafts organized.

Fastio operates on a usage-based pricing model. Plans are Starter at $9.99/mo, Business at $49.99/mo, and Enterprise at $199.99/mo. Every organization starts with a 14-day free trial, which requires a credit card. Creating a basic user account is free, but establishing collaborative workspaces requires an organization on a paid subscription. Since all files uploaded to Fastio are indexed automatically when Intelligence Mode is enabled, the team can perform semantic searches across their email history and attachments.

When deploying a Gmail MCP server, developers frequently encounter configuration issues. The most common error is a redirect URI mismatch. This happens when the redirect URL sent by the MCP server during the OAuth flow does not match the Authorized redirect URIs configured in the Google Cloud Console. To resolve this, check the server's startup logs to identify the exact local port it is using, then add http://localhost:<port>/oauth2callback to your client ID credentials.

Another common issue is refresh token expiration. If your Google Cloud project is in the Testing status, OAuth tokens expire after 7 days. This requires the developer to re-authenticate weekly. To fix this, you can delete the local token file (typically ~/.gmail-mcp/token.json) and restart the client to trigger the browser authorization flow again. If you need a permanent connection, you must publish the app in the GCP console, which changes the status from Testing to In Production, though this may trigger verification warnings if sensitive scopes are active.

Finally, developers must handle Gmail API rate limits. The Gmail API enforces a daily quota and per-user per-minute limits. If an agent performs rapid email searches or drafts replies in a loop, the API will return HTTP 429 status codes. Developers should design their agents to handle these rate limits by implementing exponential backoff. In addition, when processing large email attachments, avoid transferring them as base64 strings inline within the MCP messages, as this can exceed token limits. Instead, write the attachments directly to a Fastio workspace via the Fastio MCP server and share the file link with other agents.