Gmail MCP Server

The Gmail MCP server connects AI agents to Gmail through the Model Context Protocol, exposing tools for reading threads, searching mail, sending messages, creating drafts, and applying labels. It authenticates via OAuth 2.0 using a Google Cloud credential. Multiple community implementations exist; GongRzhe/Gmail-MCP-Server is the most actively maintained TypeScript option as of 2026, with no official Google or Anthropic implementation available.

Email is where context goes to die. Threads, follow-ups, decisions made in reply chains three weeks ago. An AI agent without access to your inbox is working with one hand behind its back for anything that involves communication history. The Gmail MCP server bridges that gap: it connects an agent to your Gmail account, lets it search your mail, read threads, and send or draft messages on your behalf.

It is one of the more powerful connections you can give an agent, which also makes it one of the more important to configure carefully.

What the server exposes

The Gmail MCP server turns the Gmail API into a set of agent-callable tools. The exact tool names vary slightly between implementations, but the functional surface is consistent across the community builds:

Search runs a Gmail query and returns matching messages with metadata. It supports the full Gmail query syntax: from:[email protected], subject:"Q4 review", label:important after:2026/01/01, has:attachment, and any combination thereof. This is genuinely powerful because Gmail's search index is very good and the query language covers most real filtering needs without any custom code.

Get thread / get message fetches the content of a specific thread or individual message. The agent gets the subject, sender, recipients, date, and the full message body. For threads, it gets the entire reply chain in sequence. This is the tool the agent calls after search narrows down the right messages.

Send message composes and sends a new email in your name. You specify the recipient, subject, body, and optional CC/BCC fields. The message goes out through the Gmail SMTP relay using the API, so it appears in your Sent folder the same way a manually composed email would.

Reply to thread posts a reply into an existing thread rather than starting a new conversation. The thread ID and your reply body are the inputs.

Create draft saves a message as a draft without sending it. This is the safer alternative to send for workflows where you want the agent to compose something you review before it goes out.

Label management covers listing labels, creating new ones, and applying them to messages. Labels are Gmail's organizational primitive, so this matters for agents that categorize or triage incoming mail.

Mark read/unread updates the read status of messages. Small tool, but useful in triage workflows.

A note on official status

There is no official Gmail MCP server. Google has not published one. The original Anthropic modelcontextprotocol/servers reference collection never included Gmail. Every option you'll find is community-built.

The GongRzhe/Gmail-MCP-Server repo is the most credible TypeScript implementation available as of mid-2026. It is actively maintained, has clear setup documentation, and uses the same OAuth pattern as the rest of the Google MCP ecosystem. That said, it is still a third-party implementation, which is worth knowing when you're deciding how much access to grant.

If your requirements are simpler (read and search only), a Python implementation wrapping google-api-python-client might be easier to audit and extend. Several exist in the MCP server registry. I'd look at what's been updated most recently before committing to any single implementation.

Setup walkthrough

The Gmail API setup follows the same Google Cloud Console path as the Google Drive MCP server. If you've already done that setup, you can reuse the project and add the Gmail API.

Step 1: Enable the Gmail API

At console.cloud.google.com, go to "APIs and Services" > "Enable APIs and Services" and search for "Gmail API". Enable it for your project.

Step 2: Create OAuth credentials

Under "Credentials", create an OAuth 2.0 Client ID with application type "Desktop app". Download the credentials.json file.

Step 3: Clone and build

git clone https://github.com/GongRzhe/Gmail-MCP-Server.git
cd Gmail-MCP-Server
npm install
npm run build

Step 4: Run the auth flow

On first run, the server will open a browser window for the OAuth consent screen. After you approve the requested scopes, it stores a token locally. Subsequent runs use the stored token without any browser interaction.

If you want read-only access, open the source before running and change the scope from gmail.modify to gmail.readonly:

const SCOPES = ['https://www.googleapis.com/auth/gmail.readonly'];

This limits what the agent can do even if a prompt tries to send mail. Worth the extra step if you're not planning to use the send or draft tools.

Step 5: Add to your MCP config

For Claude Desktop at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/absolute/path/to/Gmail-MCP-Server/dist/index.js"],
      "env": {
        "GMAIL_CREDENTIALS_PATH": "/absolute/path/to/credentials.json"
      }
    }
  }
}

For Claude Code, add the same block to ~/.claude/mcp.json. Restart after saving and the Gmail tools should appear.

Real use cases

Email triage and summarization. An agent can search for unread messages from the last 24 hours, read each thread, and produce a digest organized by priority or topic. If your inbox is a mess, this turns a morning inbox review from 20 minutes of scanning into a 2-minute read of the agent's summary.

Follow-up tracking. Search for threads where you were the last to reply more than five days ago. The agent can surface those and draft follow-up messages for each. This is one of the more practical applications because it handles the cognitive overhead of tracking open threads.

Drafting responses. You describe who you're writing to and the context, the agent searches for the relevant thread to understand the history, and writes a draft reply. The draft appears in Gmail for you to review and send. This workflow keeps a human in the loop on send while saving the composition time.

Meeting coordination. An agent can search for scheduling threads, read the proposed times, and draft a reply confirming availability. If you combine this with access to a calendar API (when an MCP server for Google Calendar is available), the loop can close without manual intervention.

Customer support routing. For a personal domain or small business email, the agent can categorize incoming messages by topic, apply labels to route them, and draft acknowledgment responses. This only works well if the volume and types of inbound mail are predictable enough that the classification holds up.

Archival research. Searching years of email to find a contract, a specific conversation, or a technical decision someone made over email. An agent with search access can do this in seconds rather than the 10-minute manual search it would otherwise require.

Security considerations

The Gmail MCP server is one of the higher-stakes connections in the MCP ecosystem. Email is sensitive by default, send access in particular.

Start with read-only scope. If your use case for the next month is triage, summarization, and search, set gmail.readonly and do not change it until you actually need send. You can always add scope later by re-running the auth flow with expanded permissions.

Do not put credentials in version control. The credentials.json OAuth credential and the locally saved token file both need to stay off of GitHub and out of any synced folder. A .gitignore entry and keeping them in a dedicated directory outside your project root are both good habits.

Review what the agent is doing. The Gmail API call log is visible in the Google Cloud Console under "APIs and Services" > "Enabled APIs" > "Gmail API" > "Metrics". If you see unexpected send calls or searches for sensitive terms, something is off.

Agent prompt scope matters. An agent with a broad, open-ended instruction ("manage my email") will behave differently than one with a specific task ("find the invoice from Company X"). The broader the instruction, the more the agent reads through your mail to find relevant context. Be deliberate about what you ask.

Audit before production. If you're setting this up for anything beyond personal use (a shared inbox, a business account), do a dry run with read-only scope and log every tool call before enabling write or send access. The surface area of a business Gmail account is much wider than a personal one.

Pairing with other servers

Gmail MCP pairs well with any server that benefits from email context. Combined with Slack MCP, you get an agent that can check both communication channels when researching a topic. Combined with GitHub MCP, an agent can correlate email discussions about a feature with the actual code changes.

If you use Google Drive for document storage, pairing Gmail and Google Drive MCP gives the agent a good picture of both your documents and the conversations that reference them. An agent asked to research a project can search both email threads and Drive documents in one session.

For heavy email workflows, consider whether Linear MCP or Jira MCP might be a better organizing layer for task-oriented follow-ups rather than trying to use Gmail as a task tracker through MCP.

Bottom line

The Gmail MCP server is genuinely useful, but it asks you to make real decisions about access and trust. The read-only scope is easy to justify for most workflows. Send access requires more confidence in how you're prompting the agent and what it's allowed to do autonomously.

For personal use on your own inbox, this is one of the more impactful MCP integrations available because email is where so much real context lives. Set it up with read-only first, use it for a week, and decide from experience whether the send and draft tools are worth enabling.

For work use, treat it like any other system that can send mail as you. The OAuth credential, the scope, and the agent's instructions all need to be considered together, not independently.

Features

• Search Gmail using full Gmail query syntax (from:, subject:, label:, after:, etc.)
• Read email threads and individual messages with full body content
• Send emails and reply to threads
• Create and manage drafts
• Apply, create, and list Gmail labels
• Mark messages as read or unread
• OAuth 2.0 authentication scoped to your Google account
• Compatible with Claude Desktop and Claude Code via stdio transport

How to set up the Gmail MCP Server MCP server

1. Create a Google Cloud project and enable the Gmail API in the API Console
2. Create an OAuth 2.0 Desktop App credential and download credentials.json
3. Clone the repo and run npm install then npm run build
4. Run the server once to trigger the OAuth consent flow and save the token
5. Add the server block to your MCP config with the path to credentials.json
6. Restart your MCP client and verify the Gmail tools appear