charity-gmail-mcp

A remote MCP server exposing Gmail tools for one specific Google account (intended for ignat@wesolveproblems.org.uk, the We Solve Problems charity account). The point of building this is so it can run as a custom connector in Claude/Cowork, freeing up the native Gmail/Drive connector to be connected to a different Google account (e.g. the boat disposal business inbox) at the same time.

How it works (no accounts created for you, no passwords handled)

This server does not implement its own login system. It tells Claude that Google itself is the authorization server (via a standard metadata file at /.well-known/oauth-protected-resource). When you connect this server to Claude, Claude redirects you to Google's own sign-in and consent screen — you log into ignat@wesolveproblems.org.uk there, directly with Google, the same way you would for any "Sign in with Google" flow. Claude then holds the resulting Google access token and sends it to this server with every request. This server only uses that token to call the Gmail API on Google's servers — it never sees or stores a password.

You will need to do the Google Cloud Console setup yourself (step 1 below), since it requires signing into your own Google account.

---

1. Google Cloud Console setup (you do this yourself)

1. Go to console.cloud.google.com and create a new project (or reuse one you already use for this account).
2. Go to APIs & Services > Library, search for Gmail API, and click Enable.
3. Go to APIs & Services > OAuth consent screen.
   • User type: External (unless you have Google Workspace and want Internal).
   • Fill in the app name (e.g. "Charity Gmail MCP"), your support email, etc.
   • Add scopes: gmail.readonly, gmail.compose, gmail.labels.
   • Add ignat@wesolveproblems.org.uk as a test user if the app is in "Testing" publishing status.
4. Go to APIs & Services > Credentials > Create Credentials > OAuth client ID.
   • Application type: Web application.
   • Authorized redirect URI: https://claude.ai/api/mcp/auth_callback (this is Claude's own callback URL, not something you host).
   • Save. Copy the Client ID and Client Secret — you'll paste these into Claude later, not into this codebase.

---

2. Deploy this server

The server needs a public HTTPS URL that Anthropic's servers can reach (Claude connects to it from Anthropic's cloud, not from your device, even in Cowork/Desktop). Any Node host works. Render.com's free tier is the simplest to get started with — note that Render does not have an "upload a folder" button; it deploys either from a connected Git repo or a prebuilt Docker image. For a small project like this, a Git repo is the easy path:

1. Create an empty repo on GitHub and push this folder to it — or, if you'd rather keep it inside an existing bigger repo, commit this folder there at any path (e.g. tools/charity-gmail-mcp/).
2. In Render: New + > Web Service, connect that GitHub repo.
   • Build command: npm install
   • Start command: npm start
   • If this folder lives inside a bigger repo, also set Root Directory (Settings > Build & Deploy) to that folder's path, e.g. tools/charity-gmail-mcp. Build/start commands then run relative to it, and files outside it aren't visible to the service. See Render's monorepo support docs.
3. Add an environment variable PUBLIC_URL set to the URL Render assigns you, e.g. https://charity-gmail-mcp.onrender.com (no trailing slash). You may need to deploy once first to learn the URL, then set the env var and redeploy.
4. Confirm it's up by visiting https://<your-url>/.well-known/oauth-protected-resource in a browser — you should see a small JSON document.

Alternatives to Render: Railway, Fly.io, or any VPS running Node 18+. Avoid serverless platforms with cold-start file systems unless you're comfortable adapting the code — this implementation is stateless so it should actually work fine on most of them, but Cloudflare Workers specifically would need the googleapis-style calls ported to raw fetch (this code already uses plain fetch-free googleapis... see note below).

Note: this server currently talks to Gmail via the googleapis npm package. If you deploy to an edge/Workers runtime that doesn't support it, swap those calls for direct fetch() calls to https://gmail.googleapis.com/gmail/v1/... with the bearer token — the tool logic and shapes stay the same.

---

3. Add it to Claude / Cowork

1. In Claude: Customize > Connectors > "+" > Add custom connector.
2. Server URL: https://<your-deployed-url>/mcp
3. Click Advanced settings and paste the OAuth Client ID and Client Secret from step 1.
4. Click Add, then Connect.
5. You'll be redirected to Google's sign-in — log in as ignat@wesolveproblems.org.uk and approve the Gmail scopes.
6. Done. This connector now gives Claude Gmail tools for the charity account, independently of whatever account is connected via the native Gmail/Drive connector.

---

Tools this server exposes

Tool	What it does
search_messages	Search Gmail with normal Gmail search syntax
get_message	Fetch a single message's full content by ID
get_thread	Fetch a full conversation thread by ID
list_labels	List all Gmail labels
create_draft	Create a draft email (never sends — you send manually)

---

Local testing before deploying

npm install
PUBLIC_URL=http://localhost:3000 npm start

Then in another terminal:

curl http://localhost:3000/.well-known/oauth-protected-resource

You should see a JSON document listing Google as the authorization server. A POST to /mcp without an Authorization: Bearer <token> header should return 401 Unauthorized.

Limitations / things to harden if this goes beyond personal use

• No rate limiting or logging.
• If Google's access token expires mid-session, Claude handles refresh via its own OAuth client credentials flow with Google — this server doesn't need to do anything extra for that.
• Attachment content isn't exposed (matches the native Gmail connector's own limitation) — only metadata via get_message.