Gmail MCP Server (GongRzhe)
Gmail MCP with auto OAuth: send, search, label and manage email
Add to your client
Copy the config for your MCP client and paste it into its config file.
npx -y @gongrzhe/server-gmail-autoauth-mcpPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"gmail-mcp-server-gongrzhe": {
"command": "npx",
"args": [
"-y",
"@gongrzhe/server-gmail-autoauth-mcp"
]
}
}
}Before you start
- Node.js installed (run via npx, no global install required)
- A Google Cloud project with the Gmail API enabled
- OAuth 2.0 client credentials (Desktop app type recommended) downloaded as gcp-oauth.keys.json from Google Cloud Console > APIs & Services > Credentials
- For Web-app credential type: add the redirect URI http://localhost:3000/oauth2callback
- The OAuth keys file placed in the working directory or in ~/.gmail-mcp/
About Gmail MCP Server (GongRzhe)
Gmail MCP Server is a community-built Node.js server that gives MCP clients (Claude Desktop, Cursor, and others) full programmatic control over a Gmail account through the official Gmail API. Its headline feature is automatic OAuth2 handling: on first run it opens a browser, walks you through Google sign-in, and caches the resulting token, so you don't have to wire up auth flows yourself.
Beyond sending and reading, it covers the operational surface of Gmail: searching with native Gmail query syntax (e.g. from:alice has:attachment newer_than:7d), creating and editing drafts, downloading attachments, full label management, batch operations across many messages at once, and Gmail filter creation including reusable filter templates.
It supports HTML and multipart messages and international (non-ASCII) characters, making it suitable for real outbound email rather than just plain-text notes. It's installable in one line via npx or Smithery and runs locally over stdio.
Tools & capabilities (12)
send_emailSend an email, with HTML/multipart and attachment support
draft_emailCreate a draft message without sending it
read_emailRead the full content of a specific message by ID
search_emailsSearch the mailbox using native Gmail query syntax
modify_emailAdd or remove labels / change the state of a message
delete_emailPermanently delete a message
download_attachmentDownload an attachment from a message
batch_modify_emailsApply label/state changes to many messages at once
batch_delete_emailsDelete many messages in a single operation
list_email_labels / create_label / update_label / delete_label / get_or_create_labelFull label CRUD and idempotent get-or-create
create_filter / list_filters / get_filter / delete_filterManage Gmail filters programmatically
create_filter_from_templateCreate a filter from a reusable template
When to use it
- Use it when you want an AI assistant to triage your inbox — search, label, archive, and batch-clean messages by query
- Use it to draft and send real emails (HTML, attachments, international characters) from inside Claude or Cursor
- Use it to automate label and filter setup so incoming mail is sorted without manual rules
- Use it when you need to pull attachments out of specific threads programmatically
- Use it for bulk inbox cleanup via batch modify/delete across hundreds of messages
Quick setup
- 1Enable the Gmail API in a Google Cloud project and download OAuth credentials as gcp-oauth.keys.json
- 2Place gcp-oauth.keys.json in your working directory or ~/.gmail-mcp/
- 3Run `npx @gongrzhe/server-gmail-autoauth-mcp auth` and complete the browser sign-in to cache your token
- 4Add the server to your MCP client config (command: npx, args: ['@gongrzhe/server-gmail-autoauth-mcp'])
- 5Restart Claude Desktop / Cursor and verify with a search_emails or send_email call
Security notes
Requires Google OAuth client credentials and stores access/refresh tokens in plaintext under ~/.gmail-mcp/ — protect that directory. The upstream repo is archived (read-only since March 2026), so evaluate a maintained fork if you need security updates.
Gmail MCP Server (GongRzhe) FAQ
Do I have to set up OAuth manually?
You provide the Google OAuth client credentials file, but the server handles the token exchange automatically — running the `auth` command opens a browser, you sign in once, and the token is cached for reuse.
Does it work outside Claude Desktop?
Yes. It speaks MCP over stdio, so any MCP-compatible client (Cursor, etc.) works; the README also documents a Smithery one-line install for Claude.
Where do I get the credentials and is it free?
Create OAuth 2.0 credentials in Google Cloud Console with the Gmail API enabled. Google Cloud and the Gmail API are free within normal personal usage quotas; this server itself is free and MIT-licensed.
Why does sending fail with an auth/scope error?
Re-run the `auth` command to refresh the token and confirm the OAuth consent screen granted Gmail send/modify scopes; for Web-type credentials make sure http://localhost:3000/oauth2callback is an authorized redirect URI.
Can it search like the Gmail web UI?
Yes — search_emails accepts native Gmail query operators such as from:, subject:, has:attachment, and newer_than:.
Alternatives to Gmail MCP Server (GongRzhe)
Connect your personal WhatsApp: search, read and send messages and media locally
Powerful Slack MCP with stdio/SSE/HTTP, DMs, group DMs and no-admin token auth
Full Telegram user-account MCP via MTProto: read chats, manage groups, send messages
Compare Gmail MCP Server (GongRzhe) with: