gws-admin-mcp
Provides tools for managing Google Workspace resources such as users, groups, org units, roles, devices, and reports via the Admin SDK and Groups Settings API, with read-only operations by default and optional write operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gws-admin-mcp Which users haven't logged in for 90 days?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.comRuns 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:
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(orGWS_ADMIN_ALLOW_WRITE=1).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.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 withGWS_ADMIN_AUDIT=0if 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 |
Users |
|
|
Groups |
|
|
Org units |
|
|
Roles |
|
|
Domains / customer |
| — |
Devices |
|
|
Reports |
| — |
Group settings |
|
|
* 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-idThe 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)
Create a project at console.cloud.google.com (or reuse one dedicated to admin tooling).
Enable APIs: Admin SDK API and Groups Settings API (APIs & Services → Library).
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.
Create a JSON key for it (Keys tab → Add key → JSON) and save it as
~/.config/gws-admin-mcp/service-account.jsonwithchmod 600.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.settingsTell 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 doctordoctor 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 readsMCP 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 |
| 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. |
| Put the JSON key at |
| Add |
| The impersonated user is not a super-admin, or the Admin SDK API isn't enabled in the Cloud project. |
| 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 |
A delete/wipe call returns | Working as intended — re-issue the call with |
Client shows the server as failed on startup | Run |
Security notes
The service-account key impersonates a super-admin with org-wide power. Treat
service-account.jsonlike a domain-admin password: keep it out of git (this repo's.gitignorealready excludes key files,.env, andconfig.json), keep itchmod 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).
Available Tools
17 toolscustomer_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
Scored across 17 tools
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.
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.
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.
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
Read-only Google Search Console MCP server for AI assistants.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server that exposes 17 Google Workspace APIs (e.g., Gmail, Drive, Calendar) as auto-generated tools for AI assistants, enabling natural language control of Google services.-
- FlicenseNot gradedqualityDmaintenanceA production-ready MCP server that gives AI assistants full, authenticated access to the entire Google Workspace ecosystem.-
- AlicenseNot gradedqualityCmaintenanceAn admin-oriented Model Context Protocol server for Google Workspace that lets LLMs perform directory and user lifecycle operations with safety guardrails and audit logging.MIT
- AlicenseBqualityCmaintenanceA local MCP server that acts as a secure credential-holding gateway to Google APIs (Gmail, Calendar, Drive), with deny-by-default policy enforcement so agents never see OAuth tokens.13MIT