MCP Google Workspace

mcp-google-workspace

MCP server for Google Workspace APIs with per-project safety policies.

Documentation | Quick Start | API Reference

Gives AI agents controlled access to Drive, Gmail, Calendar, Sheets, Docs, and other Google services through the Model Context Protocol. A JSON policy file scopes what each project can access — parameter-level constraints, method denylists, and global read-only mode. An interactive wizard and policy templates make setup easy. Audit logs, SIGHUP reload, and human-readable write explanations make it production-ready.

Protocol Support

The server auto-detects the client's protocol era and adapts accordingly.

Architecture

See docs/architecture.md for the full request flow diagram and multi-user deployment pattern.

Security Model

The policy engine enforces access control at the MCP layer, before any Google API call is made:

• Service allow-list: Only listed services are exposed. Everything else is denied.
• Parameter constraints: Generic allowlists on any API parameter with per-value access levels.
• Method denylists: Block specific methods (e.g., messages.delete).
• Read-only mode: Global or per-service.
• Request explanation: Write operations include a plain-English description of what they do.
• Audit log: Structured JSONL trail of every API call, allowed and denied.
• Live reload: SIGHUP reloads the policy file without restart (HTTP transport).
• Rate limiting: Per-client-IP sliding window (HTTP transport).
• Origin validation: Configurable allowlist (default: localhost only).

Google Credentials Setup

The server needs OAuth2 credentials to call Google APIs. Choose one method:

Option A: Application Default Credentials (simplest for local dev)

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/drive,\
https://www.googleapis.com/auth/gmail.modify,\
https://www.googleapis.com/auth/calendar

This stores credentials at ~/.config/gcloud/application_default_credentials.json. The server finds them automatically.

Option B: Service Account (recommended for production)

1. Go to Google Cloud Console → IAM & Admin → Service Accounts
2. Create a service account, download the JSON key file
3. Enable the APIs you need (Drive API, Gmail API, Calendar API, etc.) under APIs & Services → Enabled APIs
4. Share Drive folders or calendars with the service account's email address
5. Set the credentials path:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

Option C: OAuth2 Client Credentials (for user-scoped access)

1. Go to APIs & Services → Credentials → Create Credentials → OAuth client ID
2. Choose Desktop application, download the JSON
3. Use the gws CLI to complete the OAuth flow:

# Install gws
cargo install google-workspace-cli

# Authenticate (opens browser)
gws auth login --credentials /path/to/client-credentials.json

# Credentials are stored in the OS keyring
# The MCP server reads them automatically via `gws auth export`

You can also export credentials to a file and reference it in the policy:

gws auth export --unmasked > /path/to/credentials.json

{
  "server": {
    "credentials_file": "/path/to/credentials.json"
  }
}

Credential Priority

The server checks these locations in order:

1. GOOGLE_WORKSPACE_CLI_TOKEN env var (raw access token)
2. credentials_file from policy JSON server object
3. GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE env var
4. ~/.config/gws/credentials.json
5. gws auth export --unmasked (reads from OS keyring)
6. GOOGLE_APPLICATION_CREDENTIALS env var
7. ~/.config/gcloud/application_default_credentials.json

Quick Start

Container (recommended)

podman run -p 3000:3000 \
  -v ./gws-policy.json:/etc/mcp-google-workspace/policy.json:ro \
  -v ./credentials.json:/secrets/credentials.json:ro \
  -e GOOGLE_APPLICATION_CREDENTIALS=/secrets/credentials.json \
  ghcr.io/fabiendupont/mcp-google-workspace:latest

From Source

cargo build --release
./target/release/mcp-google-workspace --policy gws-policy.json

HTTP Transport

./target/release/mcp-google-workspace --policy gws-policy.json --http 127.0.0.1:3000

Policy File

Use a template for quick setup:

mcp-google-workspace init --template assistant > gws-policy.json

Available templates: analyst, assistant, admin-readonly, content-writer, it-admin. Use mcp-google-workspace init --template list to see descriptions.

Or run the interactive wizard:

mcp-google-workspace init

See policy.example.json for a full example with constraints.

{
  "server": { "read_only": false },
  "services": [
    {
      "name": "drive",
      "constraints": [
        { "param": "parents", "values": ["folder-id"], "access": "read-write", "location": "body" }
      ]
    },
    {
      "name": "gmail",
      "denied_methods": ["messages.delete", "messages.trash",
        "settings.updateAutoForwarding", "settings.delegates.create"]
    },
    {
      "name": "calendar",
      "constraints": [
        { "param": "calendarId", "values": ["primary"], "access": "read-write" }
      ]
    }
  ]
}

Validate before deploying:

mcp-google-workspace --check-policy gws-policy.json

Claude Code Integration

Add to .claude/settings.json:

{
  "mcpServers": {
    "google-workspace": {
      "command": "/path/to/mcp-google-workspace",
      "args": ["--policy", "/path/to/gws-policy.json"]
    }
  }
}

Kubernetes Deployment

Manifests are in deploy/kubernetes/. Deploy with:

# Create the credentials secret first
kubectl create secret generic mcp-gws-credentials \
  --from-file=credentials.json=./your-credentials.json \
  -n mcp-google-workspace

# Deploy
kubectl apply -k deploy/kubernetes/

Each user gets their own deployment with their own credentials Secret and policy ConfigMap. See docs/architecture.md for the multi-user deployment pattern.

Endpoints

Observability

• Structured logging via tracing (stderr, RUST_LOG for filtering)
• OpenTelemetry traces via OTLP/HTTP (set OTEL_EXPORTER_OTLP_ENDPOINT)
• Prometheus metrics at /metrics (request count, latency, errors, active tasks)

How It Works

The server is discovery-driven: it fetches Google Discovery Documents at runtime to learn each API's resources, methods, and parameters. No hardcoded API list — new endpoints appear automatically.

Each enabled Google service is exposed as a single MCP tool. The agent specifies resource and method as arguments:

{
  "name": "drive",
  "arguments": {
    "resource": "files",
    "method": "list",
    "params": { "q": "mimeType='application/pdf'", "fields": "files(id,name)" }
  }
}

A gws_discover meta-tool lets the agent introspect available resources, methods, and parameter schemas before making calls.

License

Apache-2.0