Google Workspace MCP Server (gws-mcp)

A lightweight, robust Model Context Protocol (MCP) server wrapping the Google Workspace CLI (gws). It gives LLMs and AI agents (Claude Desktop, Cursor, Pi, VS Code, Goose) dynamic access to all Google Workspace APIs (Drive, Gmail, Docs, Sheets, Calendar, Admin, and more).

Features

• ⚡ Zero Context Bloat: Dynamic API discovery via Discovery Documents avoids registering dozens of static tools in LLM context.

• 🔒 Security & Isolation: Strict argument validation prevents flag/command injection.

• ⏱️ Process Safety: Built-in process execution timeouts, signal escalation (SIGTERM/SIGKILL), multi-byte UTF-8 stream decoding, and memory buffer bounds.

• 🛡️ Safety & Dry-Runs: Full support for --dry-run, Google Cloud Model Armor --sanitize, and rate-limit --page-delay-ms.

• 🔑 Preflight Auth Inspection: Built-in gws_auth_status tool to check active OAuth tokens, identity, and granted scopes.

Related MCP server: Google Workspace MCP Server

Prerequisites

1. Node.js: v18.0.0 or higher.

2. gws CLI: The official Google Workspace CLI installed and authenticated.

   • Install gws: https://github.com/googleworkspace/cli

   • Authenticate: gws auth login or configure service account credentials.

Quickstart (npx)

Run without cloning:

npx -y @ervinpopescu/gws-mcp

Or install globally:

npm install -g @ervinpopescu/gws-mcp
gws-mcp

Client Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "@ervinpopescu/gws-mcp"],
      "env": {
        "PATH": "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

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

Pi Coding Agent (~/.pi/config.json)

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

VS Code (Cline / Roo Code)

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

Goose (~/.config/goose/config.yaml)

extensions:
  google-workspace:
    name: Google Workspace
    cmd: npx
    args:
      - -y
      - "@ervinpopescu/gws-mcp"
    enabled: true

Available Tools

1. gws_command

Executes an arbitrary command against Google Workspace APIs.

2. gws_schema

Queries the API schema for a specific endpoint to inspect parameter specifications and response structures.

3. gws_auth_status

Inspects active authentication status, user email, token validity, and granted OAuth scopes.

Environment Variables

Troubleshooting

gws CLI executable was not found in PATH

GUI applications on macOS (Claude Desktop, Cursor) do not inherit shell profile $PATH definitions (.zshrc/.bashrc). Pass the explicit PATH containing gws in your env configuration:

"env": {
  "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
}

Development & Testing

# Clone the repository
git clone https://github.com/ervinpopescu/gws-mcp.git
cd gws-mcp

# Install dependencies
npm install

# Run automated tests
npm test

License

GNU General Public License v3.0 © 2026 Ervin Popescu