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

Field	Description
listen_addr	HTTP listen address and port, e.g. 0.0.0.0:8080
oauth_callback_url	Full public URL of the OAuth callback, served on the same port
gmail.local_path	URL path prefix for the Gmail MCP endpoint
gmail.visibility_cutoff_date	Oldest visible Gmail date for thread reads in YYYY-MM-DD format
gmail.allowed_recipients	Allowlist of recipient addresses. Use ["*"] to allow all
calendar.local_path	URL path prefix for the Calendar MCP endpoint
oauth.client_id	Google OAuth client ID
oauth.client_secret	Google OAuth client secret
oauth.token_dir	Directory where the token file is persisted
oauth.allowed_account_emails	Google account emails allowed to complete first-run OAuth

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

Endpoint	URL
Gmail MCP	http://<host>:8080/gmail/mcp
Calendar MCP	http://<host>:8080/calendar/mcp

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

Tool	Description
search_threads	Search Gmail threads
get_thread	Fetch a thread by ID
list_drafts	List drafts
create_draft	Create a new draft

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

Tool	Description
list_calendars	List accessible calendars
list_events	List events in a calendar
get_event	Fetch a single event
suggest_time	Find an available time slot
create_event	Create a new event
update_event	Update an existing event
respond_to_event	Accept, decline, or tentatively accept an invitation