Log inSubmit server
Gmail MCP logo

Gmail MCP

Connects AI clients to Gmail for searching, reading, drafting, sending, labeling, and reversible trash management.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Gmail MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "gmail-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-google-gmail@latest"
      ],
      "env": {
        "GOOGLE_GMAIL_CLIENT_ID": "YOUR_VALUE_HERE",
        "GOOGLE_GMAIL_CLIENT_SECRET": "YOUR_VALUE_HERE",
        "GOOGLE_GMAIL_REFRESH_TOKEN": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

Gmail MCP MCP server connects AI applications to a Google Gmail account through the Gmail API. It provides 24 tools for searching and reading messages and threads, managing drafts, sending email, organizing labels, and moving mail to or from the trash. OAuth can be initiated from the conversation using a local PKCE redirect, while draft review separates preparation from sending. Reach for it when an agent needs mailbox triage or controlled email actions without permanent message deletion.

Use cases

  • Triage unread messages from a recent date range
  • Draft and review replies before sending
  • Organize messages with labels and archive state
  • Restore messages from the Gmail trash
  • Inspect threads and attachment metadata

Key features

  • Gmail API access through MCP
  • Search and read messages and threads
  • Draft-first email sending workflow
  • Label and mailbox-state management
  • Reversible trash operations
  • Bounded message-body and attachment handling

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

12/12 checks healthy over the last 66d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 4d ago via OSV.dev · mcp-google-gmail@latest (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

npm downloads1kPackage downloads in the last 30 days.
Last commit7d agoMost recent push to the default branch.
Directory activity2 viewsConfig copies, upvotes, and views on AllMCPs.

How Gmail MCP works

What Gmail MCP does

Gmail MCP exposes Gmail mailbox operations through the Model Context Protocol. It supports searching and reading messages and threads, inspecting drafts and labels, viewing the mailbox profile, sending messages, and managing mailbox organization. The server includes 24 tools covering common Gmail workflows.

Email composition can follow a reviewable draft process: create a draft, inspect it, update it if needed, and send it as a separate action. Direct sending is also available through send_message. Draft updates replace the complete draft because Gmail does not provide partial draft editing.

Mailbox cleanup uses Gmail’s trash rather than permanent message deletion. Messages and threads can be trashed or restored for roughly 30 days. Draft deletion and label deletion are permanent operations, and sending cannot be undone.

How it works

The server communicates with Gmail using the Gmail API and the Google account that authorized its token. Authentication can begin from the conversation when the user asks to connect Gmail. The flow guides OAuth client setup, receives Google’s redirect on 127.0.0.1, uses PKCE, and stores the tokens without requiring a configuration file or server restart.

Read operations include Gmail query syntax and return mailbox information such as senders, subjects, dates, snippets, and message content. Decoded bodies are limited to a configurable size and include indicators when truncation occurs. Attachments are returned as metadata; retrieving attachment content requires the raw_request tool.

The client can distinguish read, write, and destructive operations and decide when to request confirmation. After an ambiguous send failure, the server does not retry automatically. Searching in:sent before retrying helps avoid sending the same email twice.

Setup and configuration

Node.js 20 or newer and a Google account are required. Install the package as an MCP stdio server with:

Terminal
npx -y mcp-google-gmail@latest

Codex, Claude Code, Claude Desktop, Cursor, and VS Code configurations are documented with this command. Claude Desktop uses its local JSON configuration on builds that support local MCP configuration; the package does not include a .mcpb extension bundle.

Authentication values can be supplied with GOOGLE_GMAIL_CLIENT_ID, GOOGLE_GMAIL_CLIENT_SECRET, and GOOGLE_GMAIL_REFRESH_TOKEN. Alternatively, the conversation-led connection flow handles OAuth setup after the server is added to the client.

The server requests the gmail.modify Google scope. That scope supports mailbox changes while excluding Gmail settings access and permanent message deletion.

Tools and capabilities

  • Search messages with Gmail query syntax and read messages or threads.
  • Create, inspect, update, send, and permanently delete drafts.
  • Send email directly, including recipient and CC workflows.
  • Create, rename, apply, and remove labels.
  • Change read, starred, archived, and label state.
  • Move messages or threads to and from the trash.
  • Make deliberate raw Gmail API requests through raw_request.

Limitations and notes

All operations apply to one mailbox: the account associated with the authorized token. Sending email is irreversible, and the server does not claim that a sent message can be recalled. Trashing is reversible for about 30 days, but deleting a draft or label bypasses the trash. Message bodies are bounded by a configurable limit, and attachment data is not included directly in normal results.

Raw API requests can perform operations without a dedicated tool and may be destructive. The AI client, rather than the server alone, controls confirmation prompts. When a send times out or returns a 5xx error, verify the Sent folder before attempting another send.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Gmail MCP

Gmail MCP is an MCP server that connects AI applications to a Google Gmail account through the Gmail API. Its main tools search and read messages and threads, create and manage drafts, send email, organize labels, and move messages to or from trash. It also supports controlled raw API requests.

Install it as a stdio server with `npx -y mcp-google-gmail@latest`, then add that command to an MCP client such as Codex, Claude Code, Claude Desktop, Cursor, or VS Code. Node.js 20 or newer and a Google account are required.

Yes, Gmail MCP works with Cursor through a stdio entry in `~/.cursor/mcp.json` on macOS or Linux, or the corresponding user directory on Windows. Configure the command as `npx` with `-y` and `mcp-google-gmail@latest` as its package argument.

Yes, `send_message` sends an email directly without the draft workflow. For review before delivery, create a draft, inspect or update it, and then call `send_draft`. Sending is destructive because Gmail cannot recall the delivered message.

No, message and thread removal uses Gmail’s trash, which can generally be reversed for about 30 days. The server has no permanent message-delete tool. Deleting a draft or label is different: those operations are permanent and bypass the trash.

Related MCP servers

All in Communication All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewGmail MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/gmail-mcp?style=directory)](https://allmcps.com/mcp/gmail-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/gmail-mcp"><img src="https://allmcps.com/api/badge/gmail-mcp?style=directory" alt="Gmail MCP on AllMCPs" /></a>