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 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 (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 (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, 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 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).