Content
# 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](https://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):
```bash
npm install -g wrangler
wrangler login
```
Clone this repo, then create a KV namespace for token storage:
```bash
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:
```bash
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:
```bash
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`):**
```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`):**
```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:**
```bash
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.
