gws-admin-mcp

gws-admin-mcp

A local Model Context Protocol (MCP) server that gives your AI agent (Cursor, Claude Desktop, or any MCP client) a safe Google Workspace admin console. It talks to the Admin SDK (Directory, Reports, Groups Settings) through a service account with domain-wide delegation, so the agent can answer questions like "which users haven't logged in for 90 days?" or "who is in the Finance group?" — and, only when you explicitly allow it, make changes.

MCP client ──stdio──► gws-admin-mcp ──service account JWT (impersonates an admin)──► admin.googleapis.com / groupssettings.googleapis.com

Runs entirely on your machine. No third-party service, no telemetry, no data leaves your laptop except the Google API calls themselves.

Safety model

This server assumes the agent driving it is fallible. Three layers:

1. Read-only by default. Out of the box only the 17 read tools are registered — write tools are not hidden behind a runtime check, they simply do not exist in the tool list, so the agent cannot call them. Mutations require starting the server with --allow-write (or GWS_ADMIN_ALLOW_WRITE=1).
2. Confirm gate on destructive calls. Even with writes enabled, the irreversible operations — users_delete, groups_delete, orgunits_delete, role_assignment_delete, mobile device wipe actions, and ChromeOS deprovision — are refused unless the call includes "confirm": true. The agent has to make the destructive intent explicit a second time.
3. Audit log. Every tool call is appended as JSON lines to ~/.config/gws-admin-mcp/audit.log (mode 600), with passwords and secrets redacted. Disable with GWS_ADMIN_AUDIT=0 if you must.

Recommended pattern: run the read-only instance permanently, and start a second, write-enabled instance only for the duration of a change window.

Tools (40 total; 17 in read-only mode)

* Destructive — additionally requires "confirm": true in the call (device tools only for wipe/deprovision actions).

List tools auto-paginate up to a maxResults cap, and users_list supports the full Admin SDK search syntax (orgUnitPath='/Sales', isAdmin=true, email:jdoe*, ...).

Requirements

• Node.js >= 20
• Super-admin access to a Google Workspace domain (to grant domain-wide delegation)
• A Google Cloud project (free — the Admin SDK has no usage cost)

Google Cloud setup

You need a service account whose key the server uses to impersonate a Workspace super-admin. Two paths:

Path A — scripted (needs gcloud)

gcloud auth login [email protected]scripts/setup-service-account.sh [email protected] your-project-id

The script creates/reuses the project, enables the Admin SDK + Groups Settings APIs, creates the service account, writes the key and config to ~/.config/gws-admin-mcp/, and prints the client ID + scope string for the final manual step (step 5 below — Google provides no API for that part).

Path B — manual (Cloud console)

1. Create a project at console.cloud.google.com (or reuse one dedicated to admin tooling).
2. Enable APIs: Admin SDK API and Groups Settings API (APIs & Services → Library).
3. Create a service account (IAM & Admin → Service Accounts → Create). No project-level IAM roles are needed — its power comes entirely from the delegation grant in the next steps.
4. Create a JSON key for it (Keys tab → Add key → JSON) and save it as ~/.config/gws-admin-mcp/service-account.json with chmod 600.
5. Grant domain-wide delegation — this is the step people miss:
   • Copy the service account's OAuth 2 client ID (a long number, shown on the service account details page).
   • In the Admin console (admin.google.com): Security → Access and data control → API controls → Domain-wide delegation → Add new.
   • Paste the client ID, and paste this exact scope list as one comma-separated line:

https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.group,https://www.googleapis.com/auth/admin.directory.group.member,https://www.googleapis.com/auth/admin.directory.orgunit,https://www.googleapis.com/auth/admin.directory.rolemanagement,https://www.googleapis.com/auth/admin.directory.domain.readonly,https://www.googleapis.com/auth/admin.directory.customer.readonly,https://www.googleapis.com/auth/admin.directory.device.mobile,https://www.googleapis.com/auth/admin.directory.device.chromeos,https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/admin.reports.usage.readonly,https://www.googleapis.com/auth/apps.groups.settings

6. Tell the server which admin to impersonate. Create ~/.config/gws-admin-mcp/config.json:

{  "delegatedAdmin": "[email protected]",  "customerId": "my_customer"}

delegatedAdmin must be a super-admin of the domain. my_customer resolves to that admin's own organization.

Environment variables override the config files: GOOGLE_SA_KEY (key path), DELEGATED_ADMIN, CUSTOMER_ID, GWS_ADMIN_CONFIG_DIR (alternate config directory). See .env.example.

Build and verify

npm installnpm run buildnode dist/cli.js doctor

doctor checks the key, mints a delegated token, and runs sample reads against users, domains, roles, and the audit reports API. All four should say PASS. Then optionally:

npm run smoke   # spawns the real server over stdio, checks tool registration + live reads

MCP client configuration

Cursor (~/.cursor/mcp.json)

Read-only — the recommended default:

{  "mcpServers": {    "gws-admin": {      "command": "node",      "args": ["/ABSOLUTE/PATH/TO/gws-admin-mcp/dist/cli.js", "serve"]    }  }}

Write-enabled (use deliberately, ideally as a second entry you toggle on):

{  "mcpServers": {    "gws-admin-write": {      "command": "node",      "args": ["/ABSOLUTE/PATH/TO/gws-admin-mcp/dist/cli.js", "serve", "--allow-write"]    }  }}

Claude Desktop (claude_desktop_config.json)

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{  "mcpServers": {    "gws-admin": {      "command": "node",      "args": ["/ABSOLUTE/PATH/TO/gws-admin-mcp/dist/cli.js", "serve"]    }  }}

Restart the client after editing. You should see the gws-admin server with 17 tools (read-only) or 40 (write-enabled).

Troubleshooting

Security notes

• The service-account key impersonates a super-admin with org-wide power. Treat service-account.json like a domain-admin password: keep it out of git (this repo's .gitignore already excludes key files, .env, and config.json), keep it chmod 600, and rotate it periodically.
• Prefer a dedicated Cloud project for this service account so the key is easy to audit and revoke.
• Keep the permanent instance read-only. Enable writes in a separate instance only when you actually intend to change things, and turn it off after.

License & purchase

This repository is source-available, not open source: the code is public so you can read and audit every line before trusting it with a super-admin credential, but using it requires a license.

• Buy a license ($34): antchoutine.gumroad.com/l/gws-admin-mcp — perpetual, includes the full write-enabled edition and updates.
• Try it free: the read-only edition (17 tools, no mutating code) is on npm as gws-admin-mcp.

See LICENSE for the exact terms (no redistribution, no offering it as a hosted service).