# 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

```sh
npm install
```

## Run the test suite

```sh
npm test
```

## Type-check

```sh
npm run typecheck
```

## Lint and format

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

## Build

### Compile TypeScript

```sh
npm run build
```

### Build the Docker image

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

### Publish the Docker image

```sh
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

```json
{
  "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

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

```sh
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`:

```sh
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:

```sh
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

```yaml
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

```json
{
  "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 |