Gws Admin MCP

What gws-admin-mcp MCP server does

The gws-admin-mcp MCP server gives an MCP client access to Google Workspace administration functions without requiring a hosted intermediary. It connects to Google’s Admin SDK services for Directory, Reports, and Groups Settings, then exposes those operations as MCP tools over stdio.

The default mode registers 17 read-only tools. These cover users, groups, organizational units, roles, domains, customer information, mobile and ChromeOS devices, usage and audit reports, and group settings. List operations paginate automatically up to a configured maximum, and user searches accept Admin SDK query syntax such as organizational unit, administrator status, and email patterns.

How it works

The process runs on the local machine and sends Google API requests using a service-account key. The service account impersonates the Workspace administrator identified in the configuration, which requires domain-wide delegation and the required Google API scopes. Data is not sent to a separate service; outside of the Google API calls, the README states that the server has no telemetry or third-party service.

Write tools are absent from the MCP tool list unless the process starts with --allow-write or GWS_ADMIN_ALLOW_WRITE=1. This is a registration-time restriction rather than only a prompt or runtime convention. With writes enabled, deletion, device wipe, ChromeOS deprovisioning, and other irreversible operations additionally require confirm: true in the request.

Every tool call is recorded as JSON lines in ~/.config/gws-admin-mcp/audit.log with restrictive file permissions. Passwords and secrets are redacted. Logging can be disabled with GWS_ADMIN_AUDIT=0.

Setup and configuration

The gws-admin-mcp MCP server requires Node.js 20 or newer, a Google Cloud project, and super-admin access to the target Workspace domain. The Google Cloud project must enable both the Admin SDK API and Groups Settings API. A service-account JSON key is normally stored at ~/.config/gws-admin-mcp/service-account.json with restrictive permissions.

Domain-wide delegation must be granted in the Google Admin console using the service account’s OAuth 2 client ID and the scopes listed by the project. The local configuration identifies the administrator to impersonate and the customer organization, for example with delegatedAdmin and customerId in config.json.

Environment variables can override the configuration files: GOOGLE_SA_KEY selects another key path, DELEGATED_ADMIN selects the impersonated administrator, CUSTOMER_ID selects the customer, and GWS_ADMIN_CONFIG_DIR changes the configuration directory. After installing dependencies, build the project with npm run build, then validate credentials and sample reads with node dist/cli.js doctor.

Tools and capabilities

Read-only capabilities include:

• Listing and retrieving users, groups, group members, organizational units, roles, domains, and customer data.
• Creating, updating, suspending, unsuspending, moving, deleting, and resetting users when write mode is enabled.
• Managing groups, memberships, organizational units, role assignments, and group settings.
• Listing mobile and ChromeOS devices and performing supported device actions in write mode.
• Reading audit activity and user or customer usage reports.

Cursor and Claude Desktop can start the local process using a client MCP configuration that invokes node dist/cli.js serve. A separate write-enabled client entry can be used for controlled change windows.

Limitations and notes

The server depends on Google Workspace administrator permissions, correct domain-wide delegation, an accessible service-account key, and enabled APIs. The impersonated identity must be a super-admin according to the setup instructions. Google propagation delays can affect new delegation grants.

Writes are deliberately not available in the default process. Destructive requests without confirm: true are rejected even when write mode is enabled. The Google Cloud project itself is described as free, and the Admin SDK is stated to have no usage cost, but Google account, cloud, or organizational policies are outside the server’s control.