Gmail MCP Server

Streamable HTTP MCP server for Gmail — search threads, read messages, manage drafts, and organize your inbox.

Author: overment

[!WARNING] You connect this server to your MCP client at your own responsibility. Language models can make mistakes, misinterpret instructions, or perform unintended actions. Review tool outputs, verify results in Gmail, and prefer small, incremental writes.

The HTTP/OAuth layer is designed for convenience during development, not production-grade security. If deploying remotely, harden it: proper token validation, secure storage, TLS termination, strict CORS/origin checks, rate limiting, audit logging, and compliance with Google OAuth policies.

Notice

This repo works in two ways:

• As a Node/Hono server for local workflows
• As a Cloudflare Worker for remote interactions

For production Cloudflare deployments, see Remote Model Context Protocol servers (MCP).

Motivation

Gmail's API is powerful but not LLM-friendly out of the box. This server focuses on:

• Let LLMs understand inbox state in a single action (inbox_overview) instead of multiple queries
• Provide enriched search results with subject, sender, date — not just thread IDs
• Support batch operations (modify_thread handles up to 100 threads at once)
• Map API responses into human-readable feedback useful for both LLM and user
• Safer write flow: drafts first, send explicitly

In short, it's not a direct mirror of Gmail's API — it's tailored so AI agents know exactly how to use it effectively.

Features

• ✅ Overview — Get inbox stats + highlights (unread, starred, recent threads)
• ✅ Search — Find threads with Gmail query syntax, enriched results
• ✅ Read — Get full threads and messages with body content
• ✅ Labels — Discover label IDs for filtering and organizing
• ✅ Modify — Batch archive, star, mark read/unread (up to 100 threads)
• ✅ Drafts — Create, update, and send drafts with reply threading
• ✅ OAuth 2.1 — Secure PKCE flow with RS token mapping
• ✅ Dual Runtime — Node.js/Bun or Cloudflare Workers

Design Principles

• LLM-friendly: Tools are simplified, not 1:1 Gmail API mirrors
• Discovery-first: inbox_overview and list_labels help avoid guessing
• Batch-first: modify_thread accepts arrays to minimize tool calls
• Safer writes: Drafts first, send explicitly
• Clear feedback: Summaries with structured content and next steps

Installation

Prerequisites: Bun, Node.js 24+, a Google account, and a Gmail-enabled Google Cloud project. For remote: a Cloudflare account.

Ways to Run (Pick One)

1. Local + OAuth (recommended)
2. Cloudflare Worker (wrangler dev) — Local Worker testing
3. Cloudflare Worker (deploy) — Remote production

1. Local + OAuth (Recommended)

1. Go to Google Cloud Console
2. Create a project and enable the Gmail API
3. Create OAuth 2.0 Client ID (Web application)
4. Set redirect URIs:

   http://127.0.0.1:3001/oauth/callback
   alice://oauth/callback
   

5. Copy Client ID and Secret

cd gmail-mcp
bun install
cp env.example .env

Edit .env:

PORT=3000
AUTH_ENABLED=true
AUTH_STRATEGY=oauth

PROVIDER_CLIENT_ID=your-client-id.apps.googleusercontent.com
PROVIDER_CLIENT_SECRET=your-client-secret
PROVIDER_ACCOUNTS_URL=https://accounts.google.com

OAUTH_AUTHORIZATION_URL=https://accounts.google.com/o/oauth2/v2/auth
OAUTH_TOKEN_URL=https://oauth2.googleapis.com/token
OAUTH_REVOCATION_URL=https://oauth2.googleapis.com/revoke
OAUTH_SCOPES=https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/gmail.compose https://www.googleapis.com/auth/gmail.modify

OAUTH_REDIRECT_URI=alice://oauth/callback
OAUTH_REDIRECT_ALLOWLIST=alice:

... [View full README on GitHub](https://github.com/iceener/gmail-streamable-mcp-server#readme)