Gmail MCP Server

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

[!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)

Local + OAuth (recommended)
Cloudflare Worker (wrangler dev) — Local Worker testing
Cloudflare Worker (deploy) — Remote production

1. Local + OAuth (Recommended)

Go to Google Cloud Console
Create a project and enable the Gmail API
Create OAuth 2.0 Client ID (Web application)

Set redirect URIs:

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

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://oauth/callback,http://127.0.0.1:3001/oauth/callback
OAUTH_EXTRA_AUTH_PARAMS=access_type=offline&prompt=consent

Run:

bun dev
# MCP: http://127.0.0.1:3000/mcp
# OAuth: http://127.0.0.1:3001

Tip: The Authorization Server runs on PORT + 1.

2. Cloudflare Worker (Local Dev)

bun x wrangler secret put PROVIDER_CLIENT_ID
bun x wrangler secret put PROVIDER_CLIENT_SECRET
bun x wrangler dev --local | cat

Endpoint: http://127.0.0.1:8787/mcp

3. Cloudflare Worker (Deploy)

Create KV namespace:

bun x wrangler kv:namespace create TOKENS

Update wrangler.toml with KV namespace ID
Set secrets:

bun x wrangler secret put PROVIDER_CLIENT_ID
bun x wrangler secret put PROVIDER_CLIENT_SECRET

# Generate encryption key (32-byte base64url):
openssl rand -base64 32 | tr -d '=' | tr '+/' '-_'
bun x wrangler secret put RS_TOKENS_ENC_KEY

Note: RS_TOKENS_ENC_KEY encrypts OAuth tokens stored in KV (AES-256-GCM).

Update redirect URI and allowlist in wrangler.toml
Add Workers URL to your Google OAuth app's redirect URIs
Deploy:

bun x wrangler deploy

Endpoint: https://<worker-name>.<account>.workers.dev/mcp

Client Configuration

MCP Inspector (quick test):

bunx @modelcontextprotocol/inspector
# Connect to: http://localhost:3000/mcp

Claude Desktop / Cursor:

{
  "mcpServers": {
    "gmail": {
      "command": "bunx",
      "args": ["mcp-remote", "http://127.0.0.1:3000/mcp", "--transport", "http-only"],
      "env": { "NO_PROXY": "127.0.0.1,localhost" }
    }
  }
}

For Cloudflare, replace URL with https://<worker-name>.<account>.workers.dev/mcp.

Tools

`get_profile`

Get the connected Gmail account email. Call to confirm which account is active.

// Input
{}

// Output
{ email: "user@gmail.com" }

`inbox_overview`

Get inbox stats + highlights for a time range. Call this first for a quick summary.

// Input
{
  days?: number;  // 1-365, default: 7
}

// Output
{
  period: "last 7 days",
  counts: { total, unread, inbox, sent, starred, important? },
  highlights?: {
    recentUnread: Array<{ id, subject?, from? }>,
    starred: Array<{ id, subject?, from? }>
  },
  meta?: { nextSteps? }
}

`list_labels`

Discover label IDs and names. Use before filtering by labelIds.

// Input
{}

// Output
{
  items: Array<{ id, name, type?, messagesTotal?, threadsTotal? }>,
  meta?: { nextSteps?, relatedTools? }
}

`search_threads`

Search threads with Gmail query syntax. Returns enriched results.

// Input
{
  query?: string;            // Gmail search: "from:alice newer_than:7d"
  labelIds?: string[];
  includeSpamTrash?: boolean;
  limit?: number;            // 1-50, default: 25
  cursor?: string;
}

// Output
{
  items: Array<{
    id, subject?, from?, date?, snippet?,
    messageCount?, isUnread?, webUrl?
  }>,
  pagination?: { hasMore, nextCursor?, itemsReturned, limit },
  meta?: { nextSteps?, hints?, relatedTools? }
}

`get_thread`

Get a full thread with all messages.

// Input
{
  threadId: string;
  format?: "minimal" | "metadata" | "full" | "raw";
  metadataHeaders?: string[];
  maxBodyChars?: number;
}

// Output
{
  thread: { id, historyId?, messageCount, messages: [...], webUrl? },
  meta?: { nextSteps?, relatedTools? }
}

`get_message`

Fetch a single message with full content.

// Input
{
  messageId: string;
  format?: "minimal" | "metadata" | "full" | "raw";
  metadataHeaders?: string[];
  maxBodyChars?: number;
}

// Output
{
  message: { id, threadId?, snippet?, headers?, body?, webUrl? },
  meta?: { nextSteps?, relatedTools? }
}

`modify_thread`

Batch add/remove labels on threads (up to 100). Supports convenience actions.

// Input
{
  threadIds: string[];        // 1-100 thread IDs
  addLabelIds?: string[];
  removeLabelIds?: string[];
  actions?: {
    archive?: boolean;        // Remove INBOX
    unarchive?: boolean;      // Add INBOX
    markRead?: boolean;       // Remove UNREAD
    markUnread?: boolean;     // Add UNREAD
    star?: boolean;           // Add STARRED
    unstar?: boolean;         // Remove STARRED
    trash?: boolean;
    untrash?: boolean;
  };
}

// Output
{
  results: Array<{ threadId, success, error? }>,
  summary: { total, succeeded, failed },
  applied: { addLabelIds?, removeLabelIds? },
  meta?: { nextSteps?, relatedTools? }
}

`create_draft`

Create a draft from structured fields or raw MIME.

// Input
{
  to?: string | string[];     // Required unless raw provided
  cc?: string | string[];
  bcc?: string | string[];
  subject?: string;
  text?: string;
  html?: string;
  threadId?: string;          // For replies
  inReplyTo?: string;         // Message-ID for threading
  raw?: string;               // base64url RFC 2822
}

// Output
{
  draft: { id, messageId?, threadId?, snippet? },
  meta?: { nextSteps?, relatedTools? }
}

`update_draft`

Replace a draft's content (Gmail drafts are immutable internally).

// Input
{
  draftId: string;
  to?: string | string[];
  cc?: string | string[];
  bcc?: string | string[];
  subject?: string;
  text?: string;
  html?: string;
  threadId?: string;
  raw?: string;
}

`send_draft`

Send a draft. Optionally update it before sending.

// Input
{
  draftId: string;
  to?: string | string[];     // Override before send
  cc?: string | string[];
  bcc?: string | string[];
  subject?: string;
  text?: string;
  html?: string;
  threadId?: string;
  raw?: string;
}

// Output
{
  sent: { id, threadId?, labelIds?, snippet?, webUrl? },
  meta?: { nextSteps?, relatedTools? }
}

Examples

1. Get inbox summary

{ "name": "inbox_overview", "arguments": { "days": 7 } }

Response:

Inbox (last 7 days): 42 unread, 156 inbox, 12 sent, 3 starred

Recent unread:
  Alice: Meeting tomorrow at 3pm
  GitHub: PR merged in project-x

Starred:
  Boss: Q4 Planning document

2. Search for unread emails from a sender

{
  "name": "search_threads",
  "arguments": {
    "query": "from:alice@example.com is:unread newer_than:7d",
    "limit": 10
  }
}

3. Read a thread

{
  "name": "get_thread",
  "arguments": {
    "threadId": "19be18067165251d",
    "format": "full"
  }
}

4. Archive multiple threads

{
  "name": "modify_thread",
  "arguments": {
    "threadIds": ["19be18067165251d", "19be17f8a2c3b4d5"],
    "actions": { "archive": true, "markRead": true }
  }
}

Response:

Modified 2/2 threads. -INBOX -UNREAD

5. Reply to a thread (draft first)

{
  "name": "create_draft",
  "arguments": {
    "threadId": "19be18067165251d",
    "to": "alice@example.com",
    "text": "Thanks, I'll be there!"
  }
}

{
  "name": "send_draft",
  "arguments": { "draftId": "r8651610029774" }
}

HTTP Endpoints

| Endpoint | Method | Purpose | |----------|--------|---------| | /mcp | POST | MCP JSON-RPC 2.0 | | /mcp | GET | SSE stream (Node.js only) | | /health | GET | Health check | | /.well-known/oauth-authorization-server | GET | OAuth AS metadata | | /.well-known/oauth-protected-resource | GET | OAuth RS metadata |

OAuth (PORT+1 for Node):

GET /authorize — Start OAuth flow
GET /oauth/callback — Provider callback
POST /token — Token exchange
POST /revoke — Revoke tokens

Development

bun dev           # Start with hot reload
bun run typecheck # TypeScript check
bun run lint      # Lint code
bun run build     # Production build
bun start         # Run production

Architecture

src/
├── shared/
│   ├── tools/
│   │   └── gmail/           # Gmail tools (shared for Node + Workers)
│   │       ├── get-profile.ts
│   │       ├── inbox-overview.ts
│   │       ├── list-labels.ts
│   │       ├── search-threads.ts
│   │       ├── get-thread.ts
│   │       ├── get-message.ts
│   │       ├── modify-thread.ts
│   │       ├── create-draft.ts
│   │       ├── update-draft.ts
│   │       └── send-draft.ts
│   ├── oauth/               # OAuth flow (PKCE, discovery)
│   └── storage/             # Token storage (file, KV, memory)
├── services/
│   └── gmail.ts             # Gmail API client
├── schemas/
│   ├── inputs.ts            # Zod input schemas
│   └── outputs.ts           # Zod output schemas
├── config/
│   └── metadata.ts          # Server + tool descriptions
├── index.ts                 # Node.js entry
└── worker.ts                # Workers entry

Troubleshooting

| Issue | Solution | |-------|----------| | "Unauthorized" | Complete OAuth flow again; refresh token may be revoked. | | "Invalid Credentials" | Ensure OAUTH_SCOPES match your Google app and user consent. | | "Insufficient Permission" | Add gmail.modify scope for modify_thread. | | "Rate Limit Exceeded" | Slow down requests; use smaller limits. | | "Thread not found" | Thread IDs expire; search again to get fresh IDs. | | Draft update fails | Drafts are immutable; updates replace the underlying message. | | OAuth does not start (Worker) | curl -i -X POST https://<worker>/mcp should return 401 with WWW-Authenticate. | | Empty search results | Check query syntax; use list_labels to verify label IDs. | | KV namespace error | Run wrangler kv:namespace create TOKENS and update wrangler.toml. |

License

MIT

MCP Servers

Gmail MCP Server

Notice

Motivation

Features

Design Principles

Installation

Ways to Run (Pick One)

1. Local + OAuth (Recommended)

2. Cloudflare Worker (Local Dev)

3. Cloudflare Worker (Deploy)

Client Configuration

Tools

`get_profile`

`inbox_overview`

`list_labels`

`search_threads`

`get_thread`

`get_message`

`modify_thread`

`create_draft`

`update_draft`

`send_draft`

Examples

1. Get inbox summary

2. Search for unread emails from a sender

3. Read a thread

4. Archive multiple threads

5. Reply to a thread (draft first)

HTTP Endpoints

Development

Architecture

Troubleshooting

License

安装包（如果需要）

Cursor 配置 (mcp.json)

Google Calendar Streamable MCP Server

Maps Streamable MCP Server

Tesla Streamable MCP Server

Files Stdio MCP Server

Gmail MCP Server

Notice

Motivation

Features

Design Principles

Installation

Ways to Run (Pick One)

1. Local + OAuth (Recommended)

2. Cloudflare Worker (Local Dev)

3. Cloudflare Worker (Deploy)

Client Configuration

Tools

get_profile

inbox_overview

list_labels

search_threads

get_thread

get_message

modify_thread

create_draft

update_draft

send_draft

Examples

1. Get inbox summary

2. Search for unread emails from a sender

3. Read a thread

4. Archive multiple threads

5. Reply to a thread (draft first)

HTTP Endpoints

Development

Architecture

Troubleshooting

License

安装包 （如果需要）

Cursor 配置 (mcp.json)

Google Calendar Streamable MCP Server

Maps Streamable MCP Server

Tesla Streamable MCP Server

Files Stdio MCP Server

`get_profile`

`inbox_overview`

`list_labels`

`search_threads`

`get_thread`

`get_message`

`modify_thread`

`create_draft`

`update_draft`

`send_draft`

安装包（如果需要）