google-workspace-mcp-sidecar

A Node.js Docker service that acts as a policy-enforcing MCP sidecar for Gmail and Google Calendar.

• Exposes a local Gmail MCP endpoint and a local Calendar MCP endpoint

• Translates MCP tool calls into direct Gmail API and Calendar API requests

• Enforces Gmail recipient policy server-side and Gmail visibility-cutoff policy on thread reads

• Keeps OAuth credentials and tokens inside the sidecar only

Requirements

• Node.js 24+

• npm 10+

• Docker (for containerized deployment)

• A Google Cloud project with Gmail API and Calendar API enabled

Install dependencies

npm install

Run the test suite

npm test

Type-check

npm run typecheck

Lint and format

npm run lint
npm run fmt:check   # check only
npm run fmt         # format in place

Build

Compile TypeScript

npm run build

Build the Docker image

docker build -t google-workspace-mcp-sidecar:latest .

Publish the Docker image

docker tag google-workspace-mcp-sidecar:latest <your-registry>/google-workspace-mcp-sidecar:latest
docker push <your-registry>/google-workspace-mcp-sidecar:latest

Configuration

The service loads a single JSON config file. The path defaults to ./config.json and can be overridden with the CONFIG_PATH environment variable.

Secret values (OAuth client ID and secret) may be provided via environment variable interpolation using ${ENV_VAR_NAME} syntax in the config file.

Example config

{
  "listen_addr": "0.0.0.0:8080",
  "oauth_callback_url": "https://example.com/oauth/callback",
  "gmail": {
    "local_path": "/gmail/mcp",
    "visibility_cutoff_date": "2026-01-01",
    "allowed_recipients": ["*"]
  },
  "calendar": {
    "local_path": "/calendar/mcp"
  },
  "oauth": {
    "client_id": "${GOOGLE_OAUTH_CLIENT_ID}",
    "client_secret": "${GOOGLE_OAUTH_CLIENT_SECRET}",
    "token_dir": "/state/tokens",
    "allowed_account_emails": ["owner@example.com"]
  }
}

Config fields

Google Cloud setup

1. Enable the Gmail API and Calendar API in your Google Cloud project

2. Configure an OAuth consent screen

3. Create an OAuth 2.0 client (type: Web application)

4. Add your oauth_callback_url as an authorized redirect URI

First-run authentication

If no valid token exists when the service starts, it prints the Google authorization URL to the terminal and listens for the OAuth callback on the same port as the MCP endpoints. Open the URL in a browser, complete the Google sign-in, and the service will persist the token and begin serving automatically. No separate script is needed.

Run the service locally

CONFIG_PATH=./config.json npm start

Run with Docker

On first run (no token present) the container prints the Google auth URL and waits for the callback on the configured port. Complete the browser flow and the container continues startup automatically.

docker run -d \
  --name google-workspace-mcp-sidecar \
  -e GOOGLE_OAUTH_CLIENT_ID=your-client-id \
  -e GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v $(pwd)/state:/state \
  -p 8080:8080 \
  google-workspace-mcp-sidecar:latest

Follow the logs to get the authorization URL: docker logs -f google-workspace-mcp-sidecar.

To select the runtime user, add --user <uid>:<gid> to docker run:

docker run -d \
  --name google-workspace-mcp-sidecar \
  --user 1000:1000 \
  -e GOOGLE_OAUTH_CLIENT_ID=your-client-id \
  -e GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v $(pwd)/state:/state \
  -p 8080:8080 \
  google-workspace-mcp-sidecar:latest

Steady-state serving

Once a token is present, start the sidecar:

docker run -d \
  --name google-workspace-mcp-sidecar \
  -e GOOGLE_OAUTH_CLIENT_ID=your-client-id \
  -e GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v $(pwd)/state:/state \
  -p 8080:8080 \
  google-workspace-mcp-sidecar:latest

The service will reuse the persisted token from /state/tokens/token.json and refresh it automatically without requiring a new manual login.

Example docker-compose.yml

services:
  google-workspace-mcp-sidecar:
    image: google-workspace-mcp-sidecar:latest
    restart: unless-stopped
    user: "1000:1000"
    environment:
      GOOGLE_OAUTH_CLIENT_ID: "${GOOGLE_OAUTH_CLIENT_ID}"
      GOOGLE_OAUTH_CLIENT_SECRET: "${GOOGLE_OAUTH_CLIENT_SECRET}"
    volumes:
      - ./config.json:/app/config.json:ro
      - ./state:/state
    ports:
      - "8080:8080"

MCP endpoint URLs

Security

This service is a sidecar, not a general-purpose internet-facing API.

Its security model is intentionally narrow:

• the sidecar owns Google OAuth credentials and tokens

• Gmail recipient policy is enforced server-side for create_draft

• Gmail visibility cutoff is enforced on thread reads

• secret-bearing files are expected to be locked down on disk

What this service intentionally does not do

The sidecar does not try to solve every access-control problem itself.

• It does not provide a full user/session/authentication layer for downstream MCP clients.

• It does not try to be safe to expose broadly to browsers or untrusted networks.

• It does not replace network-level controls, reverse-proxy policy, VPN boundaries, or firewalling.

That is intentional. The intended deployment model is a trusted local or private sidecar sitting near the MCP client that is allowed to use the authenticated Google account.

Public exposure warning

Do not expose the Gmail or Calendar MCP endpoints directly to the public internet.

Insecure deployment patterns include:

• binding the service to a public interface and publishing /gmail/mcp or /calendar/mcp

• putting the MCP endpoints behind a public reverse proxy without additional request filtering

• allowing arbitrary browsers, web pages, or untrusted clients to reach the MCP endpoints

If you expose the MCP endpoints carelessly, an attacker may be able to use the sidecar as a confused deputy against the authenticated Google account.

Only the callback should be public

The only route that is meant to be reachable from the public internet is the OAuth callback path configured by oauth_callback_url.

That route exists only to complete the Google OAuth redirect during bootstrap. The Gmail MCP endpoint and Calendar MCP endpoint should remain private and reachable only by the trusted MCP client or a tightly controlled private network path.

Recommended deployment posture:

• expose only the callback path externally

• keep /gmail/mcp and /calendar/mcp on localhost, a private container network, or behind strict network allowlists

• treat the MCP endpoints as privileged local/private control surfaces

MCP client configuration example

{
  "mcpServers": {
    "gmail": {
      "url": "http://google-workspace-mcp-sidecar:8080/gmail/mcp"
    },
    "calendar": {
      "url": "http://google-workspace-mcp-sidecar:8080/calendar/mcp"
    }
  }
}

Available MCP tools

Gmail tools

create_draft also accepts optional thread_id, in_reply_to, and references fields for threaded replies. When thread_id is provided without the reply headers, the sidecar derives them from the target Gmail thread before creating the draft.

Known limitations

• list_drafts does not enforce visibility_cutoff_date. This is an accepted exception: drafts may expose pre-cutoff id, snippet, and internalDate values by design.

• respond_to_event updates the attendee list with a read-then-patch flow. Concurrent attendee changes can be overwritten if another client updates the same event between those two calls.

Calendar tools