# Multi-Gmail MCP Server

Gives Claude one connector that can search, read, and draft email across your
3 Gmail accounts, each addressed by a short name (`personal`, `business`,
`client` by default — rename them to whatever you like in `.env`).

I've written and tested this server (it correctly speaks the MCP protocol —
initialize, tool listing, and tool calls all verified locally). What's left
is entirely account-and-credential setup that only you can do: authorizing
your own Google accounts and creating your own free hosting account.

Total setup time: 30-45 minutes, done once. Cost: $0 (free tiers throughout).

---

## Overview of what you're building

```
Claude  --->  your MCP server (hosted for free on Render.com)  --->  Gmail API
              (this repo)                                            (x3 accounts)
```

You'll do 5 things, in order:

1. Create one Google OAuth client (covers all 3 accounts)
2. Put this code on GitHub (so Render can deploy it)
3. Deploy it to Render's free tier
4. Authorize each of your 3 Gmail accounts (one click each)
5. Add it to Claude as a custom connector

---

## Step 1: Create a Google OAuth client

1. Go to [console.cloud.google.com](https://console.cloud.google.com/) and sign in with any of your 3 Gmail accounts (doesn't matter which — this is just where the app "lives").
2. Create a new project (top-left project dropdown → New Project). Name it anything, e.g. "Gmail MCP".
3. Go to **APIs & Services > Library**, search for **Gmail API**, and click **Enable**.
4. Go to **APIs & Services > OAuth consent screen**.
   - User type: **External**.
   - Fill in app name (e.g. "My Gmail MCP"), your email for support/developer contact.
   - Scopes: skip for now (you'll authorize via URL directly).
   - Test users: add all 3 of your Gmail addresses here. While the app is in "Testing" mode, only these addresses can authorize it — that's fine and actually a good safety feature.
5. Go to **APIs & Services > Credentials > Create Credentials > OAuth client ID**.
   - Application type: **Web application**.
   - Name: anything.
   - Authorized redirect URIs: leave this section open for now — you'll add the real value in Step 3 after you know your Render URL. Add a placeholder like `https://example.com/auth/callback` for now so you can save.
6. Save. Copy the **Client ID** and **Client Secret** — you'll need them in Step 3.

## Step 2: Put this code on GitHub

1. If you don't have a GitHub account, create one free at [github.com](https://github.com) (no card required).
2. Create a new empty repository (e.g. `gmail-mcp-server`).
3. Upload the contents of this folder to that repository (drag-and-drop the files on GitHub's web UI works fine, or use `git push` if you're comfortable with git).

## Step 3: Deploy to Render (free)

1. Create a free account at [render.com](https://render.com) (no card required for the free web service tier).
2. Click **New > Web Service**, connect your GitHub account, and select the repo from Step 2.
3. Settings:
   - Runtime: **Node**
   - Build command: `npm install`
   - Start command: `npm start`
   - Instance type: **Free**
4. Under **Environment**, add these variables:
   - `GMAIL_ACCOUNTS` = `personal,business,client` (or your own names)
   - `GOOGLE_CLIENT_ID` = (from Step 1)
   - `GOOGLE_CLIENT_SECRET` = (from Step 1)
   - `MCP_SHARED_SECRET` = a long random string — this locks your server down so only Claude (with the right URL) can use it. Generate one by running `node -e "console.log(require('crypto').randomUUID())"` on your own computer, or just mash the keyboard for 30 characters.
5. Click **Create Web Service**. Wait for it to build and deploy — Render will give you a URL like `https://gmail-mcp-server-xxxx.onrender.com`.
6. Go back to Google Cloud Console (Step 1, Credentials) and edit your OAuth client's **Authorized redirect URIs**, replacing the placeholder with:
   `https://gmail-mcp-server-xxxx.onrender.com/auth/callback`
   (use your actual Render URL).

**Note on the free tier:** Render's free web services go to sleep after 15 minutes of no traffic and take ~30-60 seconds to wake up on the next request. That means the first thing you ask Claude to do with Gmail in a while might feel slow the first time, then fast after. This is normal and not a bug.

## Step 4: Authorize each Gmail account

For each of your 3 accounts, visit this URL in your browser (replace `<account>` with `personal`, `business`, or `client`, and use your real Render URL):

```
https://gmail-mcp-server-xxxx.onrender.com/auth/start?account=<account>
```

Log in with that specific Gmail account when Google prompts you, and approve access. You'll land on a page showing something like:

```
Success! "personal" is now authorized.
Copy the value below and set it as an environment variable named:
  GMAIL_PERSONAL_REFRESH_TOKEN
Value:
  1//0abc...
```

Go back to Render's **Environment** tab, add that variable with that exact value, and repeat for the other 2 accounts. Render will automatically redeploy after you save environment changes.

If a page tells you no refresh token was returned, it means that Google account already approved this app before. Go to [myaccount.google.com/permissions](https://myaccount.google.com/permissions), remove the app, and try the `/auth/start` link again.

## Step 5: Add the connector to Claude

1. In Claude (or Cowork), go to **Customize > Connectors > Add > Add custom connector**.
2. Name: "Gmail (3 accounts)" or similar.
3. URL:
   ```
   https://gmail-mcp-server-xxxx.onrender.com/mcp?key=YOUR_MCP_SHARED_SECRET
   ```
   (the `key` must match the `MCP_SHARED_SECRET` you set in Render — this is what keeps the connector private to you.)
4. Click **Add**, then connect/enable it for your conversation.

## Step 6: Try it

Ask Claude something like:

> "Search my business Gmail for anything from our supplier this month"

or

> "Draft a reply in my personal account to the email about the invoice"

Claude will call `search_emails`, `read_email`, or `create_draft` with `account` set to whichever inbox you named.

---

## Tools this server exposes

- `list_connected_accounts` — lists your configured account names and whether each has completed authorization
- `search_emails({account, query, maxResults})` — Gmail search syntax (`from:`, `subject:`, `after:`, etc.)
- `read_email({account, messageId})` — full headers + plain-text body
- `create_draft({account, to, subject, body, threadId?})` — creates a draft only, never sends
- `list_labels({account})`

Sending email is intentionally not included — Claude can prepare drafts, but you send them yourself from Gmail, same as Anthropic's own native Gmail connector.

## Security notes

- Treat your connector URL (with the `?key=` in it) like a password — anyone who has it can read and draft in all 3 inboxes.
- Refresh tokens are stored only as environment variables on your own Render service, never anywhere else.
- If you ever want to revoke access, remove the app at [myaccount.google.com/permissions](https://myaccount.google.com/permissions) for the account in question, or just delete the Render service.

## If something breaks

- Visit your server's root URL (`https://gmail-mcp-server-xxxx.onrender.com/`) — it shows configured accounts and whether they're authorized.
- Check Render's **Logs** tab for error details.
- Common issue: forgetting to update the OAuth redirect URI in Google Cloud Console after Render gives you its real URL (Step 3.6).