# 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](https://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](https://render.com/docs/monorepo-support).
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

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

Then in another terminal:

```bash
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`.