Gmail MCP Server

Inbox intelligence — search, read, draft and send Gmail through your assistant with OAuth auto-setup.

Local serverstdioTypeScriptMIT 2.1k

What is the Gmail MCP server?

Email is the original productivity sink, and Gmail's search operators — mastered by approximately nobody — are the gate to its contents. The Gmail MCP server (GongRzhe's auto-auth implementation being the community standard) puts an assistant in front of your inbox with the full verb set: search with proper Gmail query syntax, read threads, draft, send, label, archive, delete, and batch-process messages at scale.

Search-plus-synthesis is where it pays off first. "Find the thread where the vendor quoted pricing and summarise the final numbers" beats manually excavating a six-month-old conversation. The assistant writes fluent Gmail queries — from:x has:attachment after:2025/01/01 — that most humans never learn, and then actually reads the results for you.

The writing side is drafting-forward, which is the correct posture for email: the assistant composes, you review, it sends. Attachment support and HTML email are covered; batch operations (label these fifty newsletters, archive everything matching this pattern) handle the hygiene work that inboxes accumulate.

Setup is Google-flavoured: create OAuth credentials in a Google Cloud project, then run the package's one-time auth command — it opens a browser, you sign in, tokens save locally and refresh themselves. The "autoauth" in the name is earned; it's the least painful Google OAuth flow in the MCP ecosystem. As with any integration that can send email as you, keep client confirmations on for send tools, and start with a label-and-draft workflow before granting the assistant fuller autonomy over your correspondence.

Query syntax worth knowing

  • Operators compose freely — newer_than:7d has:attachment larger:5M from:accounts@ is one query, and the assistant writes that reliably where a human would fall back to scrolling.
  • in:anywhere is required to reach spam and trash. A search that "finds nothing" is very often searching only the inbox while the message sits one label away.
  • Batch tools act on message IDs returned by a previous search, which means a sloppy query becomes a sloppy bulk archive. Have it list matches first, then modify.
  • The Gmail API meters quota units per user per second, and reads are far more expensive than label changes — relabelling a thousand messages is fine, fetching a thousand full bodies will hit the ceiling and need backing off.

What you can do with it

Thread archaeology

Old decisions, quotes and commitments retrieved and summarised from deep inbox history.

Assisted correspondence

Replies drafted with full thread context, sent after your review.

Inbox hygiene at scale

Newsletters labelled, stale threads archived, patterns cleaned up in batches.

Available tools

ToolWhat it does
search_emailsSearch with full Gmail query syntax
read_emailRead a message or thread, including attachments metadata
send_email / draft_emailCompose and send, or save as draft for review
modify_emailLabel, archive, mark read/unread
batch_modify_emails / batch_delete_emailsBulk label, archive or delete operations
download_attachmentSave attachments locally

How to install the Gmail MCP server

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "@gongrzhe/server-gmail-autoauth-mcp"]
    }
  }
}

One-time: place OAuth keys from Google Cloud at ~/.gmail-mcp/gcp-oauth.keys.json, then run `npx @gongrzhe/server-gmail-autoauth-mcp auth` to sign in.

Configuration

A Google Cloud project with the Gmail API enabled and OAuth keys, then the package's one-time browser auth. Node.js 18+.

Example prompts to try

  • Find emails from the accountant with attachments from the last quarter and list what they sent.
  • Summarise my unread email and tell me which three actually need replies today.
  • Draft a follow-up to the proposal thread with Acme — friendly, one paragraph, show me first.

Frequently asked questions

The OAuth tokens live locally on your machine and the server is open source, so the trust surface is auditable. The real control is behavioural: keep send confirmations on and prefer draft-then-review over autonomous sending.