MCP Servers

A collection of Model Context Protocol servers, templates, tools and more.

G
Gmail MCP Worker
by @namervin
GitHub Repo(1 stars)

Gmail MCP server for Claude — runs on Cloudflare Workers, works on mobile and all devices

Created 5/12/2026
Updated about 4 hours ago
README
View Source
Repository documentation and setup instructions

gmail-mcp-worker

A Gmail MCP (Model Context Protocol) server that runs on Cloudflare Workers. Give any Claude client -- desktop, mobile, web -- full read/write access to two Gmail accounts, with no local setup required.

Why run this as a Cloudflare Worker?

Most MCP servers are stdio processes: they run on your local machine and only work when that machine is running. This one is different.

Because it runs on Cloudflare's global edge network, it works everywhere Claude can run:

  • Claude mobile app -- connect on your phone and use Gmail tools just like on desktop
  • Claude desktop (Mac and Windows) -- no local Node process to keep running
  • Multiple machines -- same URL, same accounts, same authorized tokens on every device
  • Always-on -- no process to start, no machine to wake up

OAuth refresh tokens are stored securely in Cloudflare KV. Once you authorize an account once via a browser redirect, every Claude session on every device can use it indefinitely -- including the Claude mobile app.

Tools

| Tool | Description | |------|-------------| | gmail_get_profile | Mailbox stats (email address, message count, thread count) | | gmail_search | Search with Gmail query syntax | | gmail_read_message | Read a message by ID | | gmail_read_thread | Read all messages in a thread | | gmail_send | Send a new email (HTML body supported, attachments supported) | | gmail_reply | Reply to a message with correct threading headers | | gmail_create_draft | Save a draft | | gmail_list_labels | List all mailbox labels | | gmail_label | Add or remove labels from a message | | gmail_trash | Move a message to trash | | gmail_batch_label | Add or remove labels from multiple messages at once | | gmail_batch_trash | Trash multiple messages at once | | gmail_detect_calendar_invites | Scan a thread for .ics attachments and Google Calendar links | | gmail_list_attachments | List all attachments on a message (name, type, size, ID) | | gmail_get_attachment | Download an attachment and return its base64 content |

Every tool takes an account parameter -- the short label you configure (e.g. "personal" or "work").

Setup

1. Google Cloud credentials

Use a personal Google account for this, not a business one. The GCP project just hosts the OAuth credential -- it does not need to match the Gmail accounts you are accessing.

  1. Go to console.cloud.google.com and sign in with any Google account.
  2. Create a new project (name it anything, e.g. gmail-mcp).
  3. Go to APIs and Services and enable the Gmail API.
  4. Go to APIs and Services and create an OAuth consent screen.
    • When asked for user type, choose External (required for personal Gmail accounts -- Internal only works for Google Workspace orgs).
    • Fill in an app name (anything) and your email. Skip the logo and scopes for now.
    • On the Audience tab (in the newer GCP UI this is a separate tab, not the main page), scroll to Test users and add every Gmail address you plan to authorize.
  5. Go to APIs and Services - Credentials - Create Credentials - OAuth Client ID.
    • Application type: Web application
    • Add an authorized redirect URI: https://YOUR-WORKER-NAME.YOUR-SUBDOMAIN.workers.dev/auth/callback
  6. Copy the Client ID and Client Secret.

2. Cloudflare setup

Install Wrangler globally (not via npx -- the global install avoids auth persistence issues):

npm install -g wrangler
wrangler login

Clone this repo, then create a KV namespace for token storage:

wrangler kv namespace create GMAIL_TOKENS

Copy the namespace ID from the output. Open wrangler.jsonc and replace REPLACE_WITH_YOUR_KV_NAMESPACE_ID with it.

If you want a custom worker name (and therefore a custom URL), also update the name field in wrangler.jsonc.

3. Set secrets and deploy

Set all six secrets. Wrangler will prompt you to paste each value:

wrangler secret put GOOGLE_CLIENT_ID
wrangler secret put GOOGLE_CLIENT_SECRET
wrangler secret put ACCOUNT_1_ID        # short label, e.g. personal
wrangler secret put ACCOUNT_1_EMAIL     # full email, e.g. you@gmail.com
wrangler secret put ACCOUNT_2_ID        # short label, e.g. work
wrangler secret put ACCOUNT_2_EMAIL     # full email, e.g. you@company.com

Install dependencies and deploy:

npm install
wrangler deploy

The deploy output will show your worker URL, e.g. https://gmail-mcp-worker.YOUR-SUBDOMAIN.workers.dev.

4. Authorize each account

Visit these URLs in your browser, substituting your worker URL and account labels:

https://YOUR-WORKER.workers.dev/auth?account=YOUR_ACCOUNT_1_ID
https://YOUR-WORKER.workers.dev/auth?account=YOUR_ACCOUNT_2_ID

Google will show a sign-in screen. Sign in with the matching Gmail address.

You may see a screen that says "Google hasn't verified this app." This is normal for apps in testing mode. Click Advanced then "Go to [your app name] (unsafe)" to continue. It is your own app -- this warning is just Google's standard disclaimer for unverified OAuth apps.

When authorization completes you will see: Account "[label]" authorized successfully. You can close this tab.

5. Add to Claude

Because this is an HTTP server (not a local process), the same URL works everywhere -- Claude Code desktop, Claude.ai web, and the Claude mobile app. You just register it in different places depending on the client.

Claude.ai web and mobile:

Two ways to get there:

  • Settings route: claude.ai > Settings > Connectors/Customize > Add a Custom Connector (the + icon next to "Web")
  • Prompt field shortcut (desktop app): click the + icon next to the prompt field > Connectors > Manage Connectors > Add a Custom Connector (the + icon next to "Web")

Paste your worker URL, give it a name (e.g. "Gmail Personal"), and save. Under Advanced Settings you can leave Client ID and Secret blank -- this worker handles its own OAuth with Google and does not require Claude to authenticate to the MCP endpoint. Toggle the connector on and it will appear in your tools immediately with no restart required.

Claude Code desktop (~/.claude.json):

{
  "mcpServers": {
    "gmail-personal": {
      "type": "http",
      "url": "https://YOUR-WORKER.workers.dev/mcp"
    }
  }
}

Restart Claude Code after editing this file for the change to take effect.

Claude Code plugin scope (.mcp.json):

{
  "mcpServers": {
    "gmail-personal": {
      "type": "http",
      "url": "https://YOUR-WORKER.workers.dev/mcp"
    }
  }
}

You can register the same URL in all three places -- they all hit the same worker and the same authorized tokens.

Adding more accounts

The worker supports up to 5 accounts out of the box (ACCOUNT_1 through ACCOUNT_5). Two are required, the rest are optional. Each new account is just two more secrets.

To add a 3rd account:

wrangler secret put ACCOUNT_3_ID        # short label, e.g. business
wrangler secret put ACCOUNT_3_EMAIL     # full email, e.g. you@business.com
wrangler deploy

Then authorize it:

https://YOUR-WORKER.workers.dev/auth?account=business

Restart Claude. The new account will appear as an option in the account parameter on every tool.

To add a 4th or 5th account, repeat the same pattern with ACCOUNT_4_ID / ACCOUNT_4_EMAIL and ACCOUNT_5_ID / ACCOUNT_5_EMAIL.

To swap or rename an account, update the relevant secrets and redeploy. The old tokens in KV stay there but become unreachable (the key is tokens:OLD_ID). They do not cause any harm.

Need more than 5? Add more optional fields to the Env interface in src/types.ts and extend the getAccountEmails and getAccountIds functions following the same pattern.

Security notes

  • OAuth credentials and email addresses are stored as Cloudflare secrets, never in source code.
  • Refresh tokens live in Cloudflare KV and are never exposed through the MCP endpoint.
  • The /auth route only accepts account IDs that match your configured labels -- anything else returns a 400.
  • You control the deployment entirely -- nothing is shared with third parties.

Planned features

These are all straightforward to add -- each one is a small Gmail API call, a new tool registration, and a few lines of code. Pull requests welcome.

| Feature | Tools | Notes | |---------|-------|-------| | Mark read / unread | gmail_mark_read, gmail_mark_unread | Add or remove the UNREAD label | | Star / unstar | gmail_star, gmail_unstar | Add or remove the STARRED label | | Archive | gmail_archive | Remove the INBOX label | | Forward a message | gmail_forward | Read original, build forwarded body, send | | Unread count | gmail_get_unread_count | Quick q=is:unread search with maxResults=1, return resultSizeEstimate | | Create / delete label | gmail_create_label, gmail_delete_label | POST /labels and DELETE /labels/{id} | | Vacation responder | gmail_get_vacation_responder, gmail_set_vacation_responder | GET/PUT /settings/vacation | | Filters | gmail_list_filters, gmail_create_filter | GET/POST /settings/filters | | Send with reply-chain attachment | -- | Already supported by gmail_send -- pass attachments array |

The first five (mark read/unread, star, archive, forward, unread count) each take under 30 lines.

Cloudflare free plan

This worker runs comfortably within Cloudflare's free tier:

  • Workers: 100,000 requests/day free
  • KV: 100,000 reads/day free

A typical Claude session uses a few dozen requests at most, so you are unlikely to come close to any limit.

Quick Setup
Installation guide for this server

Install Package (if required)

npx @modelcontextprotocol/server-gmail-mcp-worker

Cursor configuration (mcp.json)

{ "mcpServers": { "namervin-gmail-mcp-worker": { "command": "npx", "args": [ "namervin-gmail-mcp-worker" ] } } }