workspace-admin-mcp

An admin-oriented Model Context Protocol server for Google Workspace. It lets an LLM (Claude, or any MCP client) perform directory/admin operations — user lifecycle and group management — through natural language, with safety guardrails and full audit logging.

Most Workspace MCP servers are end-user focused (my Gmail, my Drive). This one is built for the admin — the person who onboards, offboards, and manages groups for the whole domain via the Admin SDK.

Why

Running Workspace admin at scale means living in the Admin SDK and tools like GAM: bulk operations, offboarding runbooks, group cleanups. Those are exactly the tasks an LLM is good at describing — but you can't hand an assistant the keys to suspend accounts without guardrails. This server is the safe middle layer:

• Read-only by default. Write tools refuse unless you explicitly opt in.

• Dry-run by default. Even with writes enabled, actions are simulated until you pass dry_run=false.

• Audited. Every call — read, refused, simulated, or applied — emits a structured JSON audit line.

Related MCP server: MCP Google Workspace Server

Tools

Architecture

Claude / MCP client  ──MCP──▶  workspace-admin-mcp  ──▶  Google Admin SDK  ──▶  Workspace
                                      │
                                 guardrails  ──▶  audit log (JSON, stderr)

Full diagram and design notes in docs/architecture.md.

Quickstart (local)

git clone https://github.com/pizzacrustreviewer/GWS-MCP.git
cd workspace-admin-mcp
pip install -e ".[dev]"
pytest -q          # tests run with no credentials (in-memory fake client)

Run it against a real tenant

You need a Google Cloud service account with domain-wide delegation authorized for the directory scopes, and a Workspace admin to impersonate. Use a personal or developer tenant — never production/corporate.

cp .env.example .env      # fill in the values, then:
export $(grep -v '^#' .env | xargs)
workspace-admin-mcp       # starts on stdio for a local MCP client

Connect from Claude Desktop

{
  "mcpServers": {
    "workspace-admin": {
      "command": "workspace-admin-mcp",
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/service-account.json",
        "WORKSPACE_ADMIN_SUBJECT": "admin@yourdomain.com",
        "WORKSPACE_READ_ONLY": "true"
      }
    }
  }
}

Configuration

Deploy (optional)

The repo ships a Dockerfile and reference Terraform for Cloud Run (private ingress, least-privilege runtime SA, key mounted from Secret Manager). See terraform/. This is reference IaC — it only runs if you apply it against a project you own.

docker build -t workspace-admin-mcp .

Security

• Writes off by default; dry-run by default; explicit opt-in for both.

• Least-privilege scopes (read scopes only unless writes are enabled).

• No credentials in the image or repo; .gitignore blocks key files.

• Structured audit trail suitable for shipping to Cloud Logging.

Roadmap & limitations

This is v0.1 — the logic is complete and unit-tested; the live Admin SDK layer, pagination, and HTTP-transport auth are the next steps. See ROADMAP.md.

License

MIT — see LICENSE.