Log inSubmit server
Gmail logo

Gmail

Connects AI agents to Gmail for OAuth-authenticated email search, messaging, labels, batch actions, and CSV export.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Gmail

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-3": {
      "command": "npx",
      "args": [
        "-y",
        "@mcp-z/cli"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_VALUE_HERE",
        "GOOGLE_CLIENT_SECRET": "YOUR_VALUE_HERE",
        "AUTH_MODE": "YOUR_VALUE_HERE",
        "GOOGLE_SERVICE_ACCOUNT_KEY_FILE": "YOUR_VALUE_HERE",
        "REDIRECT_URI": "YOUR_VALUE_HERE",
        "TOKEN_STORE_URI": "YOUR_VALUE_HERE",
        "DCR_STORE_URI": "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.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

npx -y @mcp-z/cli

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 15d ago.

Overview

The Gmail MCP server connects AI clients to Gmail through OAuth or service-account authentication. It exposes tools for searching, reading, sending, replying to, labeling, and trashing messages, plus CSV export and email-related prompts. It runs over stdio or HTTP and supports Node.js 20 or later. Reach for it when an agent needs to work with Gmail messages or organize email through MCP.

Use cases

  • Search and read Gmail messages
  • Send or reply to email
  • Organize messages with labels
  • Export messages to CSV
  • Run Gmail access over HTTP

Key features

  • OAuth and service-account authentication
  • Message search and retrieval
  • Email sending and replies
  • Label and message-state management
  • CSV message export
  • Stdio and HTTP transports

Security & health

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

ActiveLast checked 3d ago

Recent health check succeeded.

6/6 checks healthy over the last 41d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 13d ago via OSV.dev · @mcp-z/cli (npm)

Adoption & maintenance

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

GitHub stars5Stargazers on the source repository.
npm downloads747Package downloads in the last 30 days.
Last commit11d agoMost recent push to the default branch.
Install checkInconclusiveDidn't respond in our test window — often a slow first install.
Directory activity5 viewsConfig copies, upvotes, and views on AllMCPs.

How Gmail works

What the Gmail MCP server does

The Gmail MCP server exposes Gmail operations to MCP-compatible clients. Its tools cover message discovery, message retrieval, sending and replying, read-state changes, trashing, label management, and CSV export. It also provides an email resource and two prompts: draft-email and query-syntax.

Available tools include:

  • message-search and message-get for finding and reading messages
  • message-send and message-respond for outbound email
  • message-mark-read and message-move-to-trash for message state changes
  • labels-list, label-add, label-delete, and categories-list for mailbox organization
  • messages-export-csv for exporting messages

The package is intended for Node.js 20 or newer. It can be started directly with npx and inspected or called through @mcp-z/cli.

How it works

The Gmail MCP server supports both stdio and HTTP transports. Stdio is suitable for local client configurations, while HTTP can expose the MCP endpoint at a configured address such as /mcp. The server negotiates either of the two protocol revisions described in the project documentation, allowing a compatible client to select the revision it supports.

Authentication normally uses Google OAuth. A local setup uses a loopback redirect by default; hosted deployments can set a public callback with REDIRECT_URI. Service-account authentication is also available. Dynamic client registration is supported for HTTP deployments using DCR mode, which requires a public base URL.

OAuth tokens and DCR registrations use storage URIs handled through keyv-registry. File storage under ~/.mcp-z/ and in-memory storage work without an additional adapter. Other storage protocols require the corresponding adapter package.

Setup and configuration

Create or select a Google Cloud project, enable the Gmail API, and create OAuth credentials. Use a Desktop app credential for stdio. For HTTP, use a Web application credential and register the callback URL. The documented OAuth scopes include OpenID, Google profile and email identity, and full Gmail access. Test users must be added to the Google Cloud consent configuration where required.

A minimal stdio configuration starts the Gmail MCP server with npx:

config.json
{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "@mcp-z/mcp-gmail"]
    }
  }
}

Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET for loopback OAuth. Service-account mode uses AUTH_MODE=service-account and a path supplied through GOOGLE_SERVICE_ACCOUNT_KEY_FILE. HTTP deployments can pass a port and configure REDIRECT_URI when a public callback is needed.

Limitations and notes

DCR mode is HTTP-only and requires a public base URL. In that mode, CSV export and the /files endpoint are disabled, and resourceStoreUri is ignored. Non-file and non-memory storage backends need an adapter installed alongside the package. The documented setup grants the mail.google.com scope, so administrators should review the access level appropriate for their deployment.

Use the client’s standard stdio or HTTP MCP configuration and complete the Google authorization flow before calling Gmail tools.

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

Gmail is an MCP server that connects AI clients to Gmail through OAuth or service-account authentication. Its main tools search and read messages, send and reply to email, manage labels and message state, move messages to trash, and export messages to CSV. It runs over stdio or HTTP.

Run it with Node.js 20 or later by using `npx -y @mcp-z/mcp-gmail` in an MCP client configuration. Add Google OAuth credentials, enable the Gmail API, configure the required scopes, and authorize the account before calling tools.

Configure `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` for the default loopback OAuth flow. Use Desktop app credentials for stdio and Web application credentials for HTTP. Set `REDIRECT_URI` when a hosted HTTP deployment needs a public callback URL.

Yes, it supports service-account authentication. Set `AUTH_MODE=service-account`, provide `GOOGLE_SERVICE_ACCOUNT_KEY_FILE` with the service-account JSON path, and start the package with the service-account authentication option.

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 AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/gmail-3?style=directory)](https://allmcps.com/mcp/gmail-3)
HTML Embed
<a href="https://allmcps.com/mcp/gmail-3"><img src="https://allmcps.com/api/badge/gmail-3?style=directory" alt="Gmail on AllMCPs" /></a>