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://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)

1. Create KV namespace:

bun x wrangler kv:namespace create TOKENS

2. Update wrangler.toml with KV namespace ID

3. 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).

4. Update redirect URI and allowlist in wrangler.toml

5. Add Workers URL to your Google OAuth app's redirect URIs

6. 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