Skip to main content
Glama

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.

Related MCP server: gworkspace-mcp

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

Area

Read-only tools

Write tools (require --allow-write)

Users

users_list, users_get

users_create, users_update, users_suspend, users_unsuspend, users_reset_password, users_make_admin, users_move_ou, users_delete*

Groups

groups_list, groups_get, groups_list_members

groups_create, groups_update, groups_delete*, groups_add_member, groups_remove_member, groups_update_member

Org units

orgunits_list, orgunits_get

orgunits_create, orgunits_update, orgunits_delete*

Roles

roles_list, role_assignments_list

role_assignment_create, role_assignment_delete*

Domains / customer

domains_list, customer_get

—

Devices

devices_list_mobile, devices_list_chromeos

devices_action_mobile, devices_action_chromeos, devices_move_chromeos

Reports

reports_activities (audit log), reports_usage_user, reports_usage_customer

—

Group settings

groupsettings_get

groupsettings_update

* 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 admin@yourdomain.com
scripts/setup-service-account.sh admin@yourdomain.com 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
  1. Tell the server which admin to impersonate. Create ~/.config/gws-admin-mcp/config.json:

{
  "delegatedAdmin": "admin@yourdomain.com",
  "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 install
npm run build
node 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

Symptom

Cause / fix

unauthorized_client when minting a token

The domain-wide delegation grant is missing, uses the wrong client ID, or its scope list doesn't cover every scope the server requests. Re-paste the full scope string from above against the SA's OAuth2 client ID. Grants can take a few minutes to propagate.

Service-account key not found at ...

Put the JSON key at ~/.config/gws-admin-mcp/service-account.json or set GOOGLE_SA_KEY to its path.

DELEGATED_ADMIN ... is not set

Add delegatedAdmin to config.json or set the DELEGATED_ADMIN env var.

403 Not Authorized to access this resource/api

The impersonated user is not a super-admin, or the Admin SDK API isn't enabled in the Cloud project.

404 from Groups Settings calls

The Groups Settings API isn't enabled in the project (it's separate from the Admin SDK).

Write tools don't appear in the client

Working as intended — start the server with --allow-write or GWS_ADMIN_ALLOW_WRITE=1.

A delete/wipe call returns Refused: ... destructive/irreversible

Working as intended — re-issue the call with "confirm": true.

Client shows the server as failed on startup

Run node dist/cli.js doctor in a terminal; it prints the exact failing check. Also confirm the args path in your MCP config is absolute.

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.

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

Available Tools

17 tools
customer_getA

Get the Workspace customer (org) info.

Inputs: no named parameters.

devices_list_chromeosC

List managed ChromeOS devices.

Inputs: query, maxResults.

devices_list_mobileC

List managed mobile devices.

Inputs: query, maxResults.

domains_listA

List the domains and domain aliases in the org.

Inputs: no named parameters.

groupsettings_getA

Get a group's access settings (who can join/post/view, archiving, moderation, etc.).

Inputs: groupEmail (required).

groups_getA

Get a group by email or id.

Inputs: groupKey (required).

groups_listB

List groups. Optional query (e.g. "email:sales*") or userKey to list groups a user belongs to.

Inputs: query, userKey, maxResults.

groups_list_membersC

List members of a group.

Inputs: groupKey (required), maxResults.

orgunits_getA

Get an org unit by path (e.g. /Sales).

Inputs: orgUnitPath (required).

orgunits_listC

List organizational units.

Inputs: type, orgUnitPath.

reports_activitiesC

Query the audit log for an application. applicationName e.g. login, admin, drive, token, groups, calendar, mobile, user_accounts, saml.

Inputs: endTime, userKey, eventName, startTime, +2 more.

reports_usage_customerA

Get the customer-wide usage report for a date (YYYY-MM-DD).

Inputs: date (required).

reports_usage_userC

Get a user usage report for a date (YYYY-MM-DD). Use 'all' for all users.

Inputs: date (required), userKey.

role_assignments_listA

List role assignments, optionally for a specific user.

Inputs: userKey.

roles_listA

List admin roles defined in the org.

Inputs: no named parameters.

users_getA

Get a single user by email or id.

Inputs: userKey (required).

users_listB

List directory users. Optional query uses Admin SDK user search syntax (e.g. "orgUnitPath='/Sales'", "isAdmin=true", "email:jdoe*").

Inputs: query, orderBy, maxResults.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 17 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action (get vs list, different resource types like users, groups, devices, reports, etc.). Even similar tools like reports_activities and reports_usage are clearly separated by audit vs usage, and device lists distinguish mobile vs ChromeOS.

    Naming Consistency5/5

    All tool names follow a consistent resource_operation pattern (e.g., users_list, groups_get, orgunits_list). Some names include a subresource (devices_list_mobile, groups_list_members), but the convention remains uniform and predictable.

    Tool Count4/5

    17 tools is a reasonable number for a Google Workspace admin server covering users, groups, devices, reports, org units, roles, and domains. It is slightly on the heavier side but each tool focuses on a distinct administrative area.

    Completeness2/5

    The tool set is almost entirely read-only (get/list/query). There are no create, update, or delete operations for users, groups, devices, org units, roles, or domains, which is a significant gap for an 'admin' server. Management tasks like creating users or updating group settings are impossible.

    Related MCP Connectors

    Related MCP Servers