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

Enable the Gmail API and Calendar API in your Google Cloud project
Configure an OAuth consent screen
Create an OAuth 2.0 client (type: Web application)
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.

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

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github/workflows		.github/workflows
src		src
test		test
.dockerignore		.dockerignore
.gitignore		.gitignore
AGENTS.md		AGENTS.md
ARCHITECTURE.md		ARCHITECTURE.md
Dockerfile		Dockerfile
README.md		README.md
config.json.example		config.json.example
knip.json		knip.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

google-workspace-mcp-sidecar

Requirements

Install dependencies

Run the test suite

Type-check

Lint and format

Build

Compile TypeScript

Build the Docker image

Publish the Docker image

Configuration

Example config

Config fields

Google Cloud setup

First-run authentication

Run the service locally

Run with Docker

Steady-state serving

Example docker-compose.yml

MCP endpoint URLs

Security

What this service intentionally does not do

Public exposure warning

Only the callback should be public

MCP client configuration example

Available MCP tools

Gmail tools

Known limitations

Calendar tools

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages