gmail-mcp-server-typescript

An authenticating proxy for Google's remote Gmail MCP server.

Google's Gmail MCP server is a managed service at https://gmailmcp.googleapis.com/mcp/v1 — there is nothing to self-host. It authenticates with OAuth 2.0, and access tokens expire hourly. OpenHuman's MCP client can hold a static credential but cannot refresh an OAuth one, and its dynamic OAuth path requires RFC 7591 dynamic client registration, which Google does not offer.

This proxy bridges that gap: it holds a long-lived refresh token, mints access tokens, and injects them upstream. Downstream it speaks plain MCP, so the client authenticates with static credentials that never expire.

OpenHuman --Basic--> Nginx Proxy Manager --> gmail-mcp-proxy:8080 --Bearer--> Google
                      (both containers on the shared `npm` network)

Design rationale, including the OpenHuman source constraints this is built around: docs/superpowers/specs/2026-08-08-gmail-mcp-proxy-design.md.

Setup

1. Google Cloud

gcloud services enable gmail.googleapis.com     --project=PROJECT_ID
gcloud services enable gmailmcp.googleapis.com  --project=PROJECT_ID

Configure the OAuth consent screen with scopes:

• https://www.googleapis.com/auth/gmail.readonly

• https://www.googleapis.com/auth/gmail.compose

Set the publishing status to "In production". While it is Testing + External, Google expires refresh tokens after 7 days and this proxy will break weekly. Verification is not required — you click through an "unverified app" warning once during consent.

Create an OAuth 2.0 Client ID of type Web application, and note the client ID and secret.

2. Configure (local only)

cp .env.example .env
$EDITOR .env     # fill in GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET

3. Mint the refresh token

One-time, using the credentials already in .env:

# Register http://localhost:8080/callback on the OAuth client first
pnpm mint

It prints an authorization URL, waits on a throwaway local callback server, exchanges the code, and prints the refresh token on its own line for easy copying. Paste it into .env as GOOGLE_REFRESH_TOKEN.

The script only ever reads .env — it never writes to it.

The script sets access_type=offline and prompt=consent. Both matter: without the first Google returns no refresh token at all, and without the second it only issues one on the first authorization for a given client+account — so a re-run appears to succeed while producing nothing usable. If you still get no refresh token, revoke at myaccount.google.com/permissions and run it again.

Alternatively use the OAuth 2.0 Playground (gear icon → "Use your own OAuth credentials"), registering https://developers.google.com/oauthplayground as the redirect URI instead.

4. Build the image

docker build -t gmail-mcp-proxy:latest .

5. Create the shared network

Nginx Proxy Manager runs in its own container, so both need a network they can address each other on. Once, on the host:

docker network create npm

Then attach the NPM container to it as well — add npm to its networks: and redeploy, or docker network connect npm <npm-container>.

6. Deploy on TrueNAS

docker-compose.yml is written for TrueNAS SCALE → Apps → Custom App. Paste it in, having replaced the three REPLACE_ME values.

Three things about that file are deliberate:

• Values are literal, not ${...}. TrueNAS has no .env beside the YAML to interpolate from, so a ${GOOGLE_CLIENT_ID} would resolve to an empty string and the container would exit at boot.

• There is no build: key. Custom apps have no build context; the image must already exist on the host, hence step 4.

• The published port is loopback-only. 127.0.0.1:40001:8080 is a debugging door on the NAS itself, not the path NPM uses — NPM is in its own container and reaches the proxy over the shared network as http://gmail-mcp-proxy:8080. See Security notes before widening it.

Verify once it's up, from the NAS:

curl localhost:40001/healthz     # => {"ok":true}

.env is only used by local development (pnpm dev) and pnpm mint. It plays no part in the deployed container.

Related MCP server: honest-gmail-mcp

Environment variables

Missing required variables abort at boot with a clear message rather than failing later as an opaque 502.

Nginx Proxy Manager

Add a Proxy Host with Forward Hostname gmail-mcp-proxy and Forward Port 8080 — the container name on the shared npm network, not a host IP and port. Nothing is published on the host, so a <truenas-ip>:<port> target would not resolve.

Access List (this is NPM's Basic auth): Access Lists → Add → Authorization tab → add a username and password, then select that list on the Proxy Host.

Leave "Satisfy Any" OFF. With it on and a LAN range in the Access tab, nginx treats IP-match or password as sufficient, so your whole LAN reaches Gmail unauthenticated. See NginxProxyManager issue #4984.

Advanced tab — required, or SSE stalls and MCP notifications arrive batched:

proxy_buffering off;
proxy_read_timeout 3600s;

OpenHuman

[[mcp_client.servers]]
name         = "gmail"
endpoint     = "https://gmail-mcp.your.lan/mcp/v1"
enabled      = true
timeout_secs = 60

  [mcp_client.servers.auth]
  kind     = "basic"
  username = "svc-openhuman"
  password = "<NPM Access List password>"

timeout_secs = 60 because a cold token refresh plus a Gmail round-trip can exceed the 30s default on the first call.

Development

pnpm install
pnpm typecheck
pnpm test          # 30 tests, no network
pnpm dev           # runs src/ directly, no build step

Troubleshooting

Security notes

• Request and response headers are filtered through an allowlist. The inbound Authorization (your NPM Basic credentials, which nginx still forwards upstream) is dropped and replaced, so it can never reach Google.

• The container runs read_only as the node user with no-new-privileges, and carries no runtime dependencies — only Node built-ins and global fetch.

• The proxy itself is unauthenticated by design; NPM's Access List is the boundary. The published port is therefore 127.0.0.1:40001 — reachable from the NAS itself for debugging, but with no route from the LAN, so the Access List stays the only way in.

• Do not change it to 40001:8080. That binds 0.0.0.0, and since the proxy injects a gmail.readonly + gmail.compose bearer onto every request it receives, any LAN host could then read or send mail without touching NPM. Docker's published-port DNAT is also evaluated ahead of host firewall rules, so a ufw/iptables deny would not close it after the fact.

• BIND_HOST is 0.0.0.0 inside the container so the NPM container can reach it over the shared network. That is not an exposure: with no published port, "all interfaces" means only the container's own network interfaces. The application defaults to 127.0.0.1 so a bare pnpm dev on your laptop is never exposed.