@sweatco/gws-cli-mcp

An MCP server that mirrors the Google Workspace CLI (gws) — but as Model Context Protocol tools instead of a shell binary. It uses the same credentials as gws and exposes the same Google API surface.

Today it wraps Google Sheets (the only service we use in production). Adding Drive, Gmail, Calendar, Docs, Chat or Admin is a single service module — see Adding a new service.

Built to migrate Archie's ops plugin off gws-via-Bash and onto a first-class MCP server. No more re-emitting env vars on every Bash call, no more shelling out to a Rust binary — the model calls typed tools directly.

Why this exists

The gws CLI is great, but driving it from an agent means shelling out through Bash, hand-assembling --params '{...}' JSON, and re-exporting credential env vars on every invocation (shell state doesn't persist between calls). An MCP server removes all of that: tools are typed and discoverable, auth is resolved once at startup, and responses come back as structured JSON.

Install / run

Runs over stdio via npx — no global install:

npx -y @sweatco/gws-cli-mcp

Add it to any MCP client. Example .mcp.json entry:

{
  "mcpServers": {
    "gws": {
      "command": "npx",
      "args": ["-y", "@sweatco/gws-cli-mcp"]
    }
  }
}

With no env set it reads ~/.config/gws/credentials.json — exactly where the gws CLI keeps credentials. Point it elsewhere with the env vars below.

Claude Code CLI:

claude mcp add gws -- npx -y @sweatco/gws-cli-mcp

Credentials

Credentials are resolved the same way the gws CLI resolves them, in this precedence order:

1. GOOGLE_WORKSPACE_CLI_TOKEN — a pre-obtained OAuth2 access token (highest priority).
2. GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE — path to a credentials JSON (service-account or authorized_user).
3. GOOGLE_WORKSPACE_CLI_CONFIG_DIR (default ~/.config/gws) — the server reads credentials.json from this directory.

So if gws already works on the machine, this server works with zero extra configuration. For a fresh headless host, point GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE at a service-account key JSON (or an authorized_user credentials file), or place that file at ~/.config/gws/credentials.json.

| Variable | Purpose | | --- | --- | | GOOGLE_WORKSPACE_CLI_TOKEN | Pre-obtained OAuth2 access token. Used as-is (no refresh). | | GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE | Path to a service-account or authorized_user JSON. ~ is expanded. | | GOOGLE_WORKSPACE_CLI_CONFIG_DIR | Config dir (default ~/.config/gws); credentials.json is read from here. |

The following are gws-mcp extensions — not gws CLI variables. The CLI derives scopes dynamically from the Discovery docs (no scope override), and it dropped domain-wide delegation / impersonation support in v0.7.0. gws-mcp re-adds both as opt-in conveniences:

| Variable | Purpose | | --- | --- | | GWS_MCP_SCOPES | Override OAuth scopes, space/comma separated. Default: https://www.googleapis.com/auth/spreadsheets. Service-account creds only. | | GWS_MCP_IMPERSONATE_SUBJECT | Domain-wide delegation subject (impersonate a Workspace user). Service-account creds only. |

Scopes note: scopes only matter for service-account / JWT credentials. An authorized_user token already carries whatever scopes were granted at consent, so GWS_MCP_SCOPES is ignored for that credential type.

The CLI's interactive, OS-keyring-encrypted login tier is intentionally not reproduced here — headless servers should use a token or a credentials file.

Tools

Google Sheets

| Tool | Mirrors | Notes | | --- | --- | --- | | sheets_get_spreadsheet | sheets spreadsheets get | Tabs, properties, merges. Use fields + ranges to scope (e.g. tab titles, merge regions). | | sheets_get_values | sheets spreadsheets values get | Read one A1 range. | | sheets_batch_get_values | sheets spreadsheets values batchGet | Read multiple ranges in one call. | | sheets_update_values | sheets spreadsheets values update | Write — overwrites a range. | | sheets_append_values | sheets spreadsheets values append | Write — appends rows after a table. | | sheets_batch_update_values | sheets spreadsheets values batchUpdate | Write — multiple ranges at once. | | sheets_clear_values | sheets spreadsheets values clear | Destructive — clears cell contents. | | sheets_batch_update | sheets spreadsheets batchUpdate | Write — structural changes (merge, format, add/delete sheets). |

gws_call — generic passthrough

A faithful, low-level mirror of gws <service> <method> --params '{...}' --body '{...}', scoped to the services enabled in the registry. Use it for any method the typed tools don't cover yet:

{
  "service": "sheets",
  "method": "spreadsheets.values.get",
  "params": { "spreadsheetId": "1L01...", "range": "Agent: Brand List!A1:Z100" }
}

params are the method's path/query parameters; body (when present) is sent as the request requestBody. The service field only accepts services that are enabled in src/registry.ts.

Mapping from the gws CLI

The translation is mechanical. CLI --params keys become tool arguments; the request --body/--json becomes values / requests / data (or body on gws_call).

# gws CLI
gws sheets spreadsheets values get --params '{"spreadsheetId":"ID","range":"Tab!A1:Z100"}'

// MCP: sheets_get_values
{ "spreadsheetId": "ID", "range": "Tab!A1:Z100" }

# gws CLI — list tab names
gws sheets spreadsheets get --params '{"spreadsheetId":"ID","fields":"sheets.properties.title"}'

// MCP: sheets_get_spreadsheet
{ "spreadsheetId": "ID", "fields": "sheets.properties.title" }

# gws CLI — write a cell
gws sheets spreadsheets values update \
  --params '{"spreadsheetId":"ID","range":"Tab!A1","valueInputOption":"USER_ENTERED"}' \
  --body '{"values":[["new value"]]}'

// MCP: sheets_update_values
{ "spreadsheetId": "ID", "range": "Tab!A1", "values": [["new value"]] }

Adding a new service

Everything flows from one registry, so a new service is one file plus one line:

1. Create src/services/<service>.ts exporting a ServiceModule:

   import { z } from "zod";
   import type { ServiceModule, ToolDef } from "./types.js";
   
   const tools: ToolDef[] = [
     {
       name: "drive_list_files",
       description: "List files. Mirrors `gws drive files list`.",
       annotations: { readOnlyHint: true, openWorldHint: true },
       inputSchema: {
         q: z.string().optional().describe("Drive query string."),
         pageSize: z.number().optional(),
       },
       handler: (a, ctx) => ctx.call("drive", "files.list", { q: a.q, pageSize: a.pageSize }),
     },
   ];
   
   export const driveService: ServiceModule = {
     service: "drive",
     version: "v3",
     scopes: ["https://www.googleapis.com/auth/drive.readonly"],
     tools,
   };

   ctx.call(service, method, params, body) is the same googleapis bridge gws_call uses, so handlers stay thin.

2. Register it in src/registry.ts:

   import { driveService } from "./services/drive.js";
   export const services: ServiceModule[] = [sheetsService, driveService];

That's it — the new tools, the service's scopes, and the gws_call service enum all update automatically. (Don't have a typed tool yet? gws_call can reach any method on a registered service immediately.)

Development

npm install      # install deps (also builds via prepare)
npm run build    # compile TypeScript to dist/
npm run dev      # watch-compile
npm run typecheck

# Smoke-test the binary
node dist/index.js --version
node dist/index.js --help

Quick stdio handshake:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"x","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | node dist/index.js

Troubleshooting

• credentials not found — set one of the credential env vars above, or place credentials.json at ~/.config/gws/.
• Error 401 / Error 403 — credentials are invalid/rotated or lack access to the resource. For service accounts, share the spreadsheet with the service-account email, or set GWS_MCP_IMPERSONATE_SUBJECT for domain-wide delegation.
• Network — the server talks to Google API hosts (sheets.googleapis.com, oauth2.googleapis.com, www.googleapis.com). Allow these if running behind an egress allowlist.
• stdout is the protocol channel — all diagnostics are written to stderr; never write to stdout from a tool.

License

MIT — see LICENSE.