google-workspace-mcp

MCP server for Google Workspace with persistent multi-account OAuth, OS keychain storage, and health monitoring.

Why

AI assistants lose Google Workspace authentication between sessions. Users with multiple Google accounts must re-authenticate manually every time. This MCP server solves both problems:

• Persistent auth — OAuth tokens stored in OS keychain, survive restarts

• Multi-account — Unlimited Google accounts with human-readable profile labels

• Health monitoring — Three-layer defense: startup check, background heartbeat, graceful tool failure

• Setup in 5 minutes — Interactive wizard handles everything

• Zero secrets in code — All credentials live in OS keychain or env vars, never on filesystem

Prerequisites

• Node.js 18+

• GCP project with OAuth 2.0 credentials (Desktop application type)

• Enabled APIs: Gmail, Calendar, Drive, Sheets, People

• OS keychain (macOS Keychain, Windows Credential Vault, or Linux libsecret) — falls back to encrypted file store

Quick Start

# Install globally
npm install -g google-workspace-mcp

# Run the setup wizard (5 minutes)
gws-mcp setup

# Or manually:
gws-mcp auth add work --scopes gmail,calendar,drive --email you@company.com
gws-mcp auth add personal --scopes gmail,drive --email you@gmail.com
gws-mcp auth status

Add to your Claude Code settings.json:

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "google-workspace-mcp"]
    }
  }
}

Available Tools

Admin Tools

Gmail

Calendar

Drive

Sheets

Contacts

Configuration

Profiles

Profiles are stored in ~/.gws-mcp/profiles.json (metadata only — no tokens):

{
  "profiles": [
    {
      "label": "work",
      "email": "you@company.com",
      "scopes": ["gmail", "calendar", "drive"],
      "rules": {
        "gmail": { "read": true, "send": true, "delete": false },
        "calendar": { "read": true, "create": true, "delete": false },
        "drive": { "read": true, "upload": true, "delete": false }
      }
    }
  ]
}

Two-Layer Permission Model

1. OAuth scopes — What Google allows (set during auth add)

2. Business rules — What you allow Claude to do (set in profiles.json or via manage_profiles tool)

Business rules are enforced even if the OAuth token technically allows more.

Notifications

Config in ~/.gws-mcp/config.json:

{
  "notifications": {
    "channels": ["desktop", "log"],
    "telegram": {
      "enabled": false,
      "botToken": "env:GWS_MCP_TELEGRAM_BOT_TOKEN",
      "chatId": "env:GWS_MCP_TELEGRAM_CHAT_ID"
    },
    "heartbeatIntervalMinutes": 30,
    "alertOn": ["reauth_needed", "token_expiring_24h", "scope_change_detected"]
  }
}

CLI Commands

gws-mcp setup                  # Interactive wizard
gws-mcp auth add <profile>     # Add account
gws-mcp auth remove <profile>  # Remove account
gws-mcp auth refresh <profile> # Force token refresh
gws-mcp auth status             # Health table
gws-mcp config show             # Show config (redacted)
gws-mcp config set <key> <val>  # Set config value
gws-mcp config reset            # Reset to defaults
gws-mcp serve                   # Start MCP server

Security

Where Secrets Live

Pre-Publish Audit

The prepublishOnly script automatically scans for leaked credentials before npm publish:

grep -rn "AIza\|ya29\.\|GOCSPX\|client_secret\|refresh_token" src/

Roadmap

See ROADMAP.md for planned features.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT