Google Workspace Admin Security Audit MCP

gwsadm-mcp

English | 日本語

Google Workspace security-audit MCP (Model Context Protocol) server — read-only visibility into account locks, suspicious logins, and external file sharing, built on the Admin SDK Reports API (audit activities).

Named after the admin-console viewpoint (gwsadm = Google Workspace admin), sibling of boxadm-mcp. This is not a general-purpose Workspace MCP: it surfaces risk and changes nothing, with one opt-in exception — sign_out_user, which exists only when the server is started with GWSADM_ENABLE_SIGN_OUT=1.

Features

Planned: dlp_events (Reports rules; requires a Workspace edition with DLP), token_events.

Auth model

Service account with domain-wide delegation (DWD) impersonating an audit-capable admin. Fully non-interactive — no browser, no token refresh rotation — so the server runs unattended (cron, MCP gateway, CI).

Grant all of the following DWD scopes on the same service-account client ID up front, in one setup pass. Adding them one at a time as each tool gets built is how a scope goes missing until the one tool that needed it starts degrading — one place, one pass, avoids the trap:

health_check needs no scope at all to respond: it is the tool to call when a grant might be missing — it probes each domain and reports the failing auth in a structured per-domain result instead of failing itself.

gmail_usage_report needs its own separate scope too, despite living under the same Admin SDK Reports API as the base pass above — the "Usage report" family (customerUsageReports) and the "Audit" activity stream (activities().list, everything else in the base pass) are gated by two different scopes, and having one does not imply the other:

gmail_message_trace and dmarc_rua_summary need one more scope, granted as a separate step — it is intentionally not bundled into the pass above:

This is a materially broader grant than the three above: it allows reading message content for any user the service account impersonates, not just metadata. gmail_message_trace only ever requests format="metadata" — it never reads a message body — but dmarc_rua_summary DOES read content: it fetches the compressed DMARC report attachment each RUA message carries (format="full" plus attachments().get()) and parses it. Both stay within what the grant allows either way, but only gmail_message_trace stays inside the narrower "metadata only" habit; the narrower gmail.metadata scope was considered and rejected for both tools because it does not support the q= search parameter the rfc822msgid:/RUA-mailbox lookups need. Grant it on the same service-account client ID as the other scopes (Admin console → Security → API controls → Domain-wide delegation → find the existing client ID → add this scope to its list), and weigh that broader exposure against how much you actually need message-trace/DMARC reporting before turning it on for a given domain.

group_delivery_policy and list_group_members each need their own separate scope too — three more grants beyond the base pass, none bundled with each other or with gmail.readonly above:

The Groups Settings API is a distinct product from the Directory API, hence the separate scope; it has no readonly-only variant, but this server only ever calls groups().get(), never a mutating method.

suspended_accounts, get_user and user_oauth_tokens all operate per configured domain (Directory domain=/userKey=), unlike the customer-wide Reports tools — so every domain you want covered (e.g. a separate student domain) needs its own [domain.*] config section. Note the failure modes differ: suspended_accounts silently omits an unconfigured domain from its result, while get_user and user_oauth_tokens fail loudly with an unknown-domain error (both take a domain override for an alias/secondary address whose suffix has no section of its own).

Setup

# uv
uv pip install gwsadm-mcp

# pip
pip install gwsadm-mcp

Or from source:

git clone https://github.com/shigechika/gwsadm-mcp.git
cd gwsadm-mcp

# uv
uv sync

# pip
pip install -e .

Configuration

Point GWSADM_CONFIG at an INI file (default ~/.config/gwsadm-mcp/config.ini, keep it 0600):

[gwsadm]
# optional; defaults to all [domain.*] section names
internal_domains = example.edu, mail.example.edu

[domain.example.edu]
service_account_file = /path/to/service-account.json
subject = [email protected]
customer_id = C0xxxxxxx
dmarc_rua_mailbox = [email protected]   # optional, default: postmaster@<domain>; "none" opts out
dmarc_rua_recipient = [email protected]   # optional, default: same as dmarc_rua_mailbox

One [domain.*] section per audited Workspace domain. internal_domains is the allowlist used to classify sharing targets as internal vs external. dmarc_rua_mailbox is the real user dmarc_rua_summary impersonates to read DMARC aggregate reports — domain-wide delegation can only act as an actual user, never as a group or alias. dmarc_rua_recipient is the address the reports are sent to (the rua=mailto: value published in the domain's _dmarc record) and is used only to narrow the Gmail search (to:<recipient>); it defaults to the mailbox. Set it when the published address is a Gmail plus-subaddress such as postmaster+rua@ (searching on it also keeps ruf= failure reports sent to postmaster+ruf@ out of the aggregate parse) or a group that fans out to the impersonated inbox. dmarc_rua_mailbox = none opts a domain out of DMARC reading — e.g. when its rua= points at another domain's mailbox that a different [domain.*] section already reads; reports are grouped by the policy domain each report names, so they still appear under that other section.

Environment variables (all optional except where noted):

Usage

Claude Code (plugin)

This repository doubles as a single-plugin marketplace, so Claude Code can install the server for you:

/plugin marketplace add shigechika/gwsadm-mcp
/plugin install gwsadm-mcp@gwsadm-mcp

The plugin launches uvx gwsadm-mcp and reads GWSADM_CONFIG (falls back to ~/.config/gwsadm-mcp/config.ini), the same variable described in Configuration. /plugin install only wires up the server process — it cannot create the config INI or the Google Cloud service-account JSON key(s) it points at; both must already exist on the machine running the plugin before any tool call will succeed.

uvx must be on the PATH of the process that runs Claude Code — a login shell usually has it, but a GUI-launched app may not; install uv system-wide if the plugin fails to start.

Claude Code (manual)

Add to .mcp.json (no env needed when the config lives at the default path; add "env": { "GWSADM_CONFIG": "..." } only for a non-default location):

{
  "mcpServers": {
    "gwsadm-mcp": {
      "type": "stdio",
      "command": "gwsadm-mcp"
    }
  }
}

Claude Desktop

Add the same entry to claude_desktop_config.json.

Codex

codex mcp add gwsadm-mcp -- gwsadm-mcp

Add --env GWSADM_CONFIG=... (before --) only if the config INI is not at the default path (~/.config/gwsadm-mcp/config.ini).

Gemini CLI

Add to ~/.gemini/settings.json (or a project's .gemini/settings.json):

{
  "mcpServers": {
    "gwsadm-mcp": {
      "command": "gwsadm-mcp"
    }
  }
}

As with Codex, add "env": { "GWSADM_CONFIG": "..." } only for a non-default config location. To expose only some tools, list them in includeTools.

Any other MCP client that launches stdio servers works the same way: give it gwsadm-mcp as the command.

Direct Execution

gwsadm-mcp

CLI Options

gwsadm-mcp --version   # Print version and exit
gwsadm-mcp --check     # Config + auth + API smoke for every domain, then exit
gwsadm-mcp             # Start MCP server (STDIO, default)

--check exit codes: 0 success, non-zero on config or auth failure.

Archiving DMARC reports (batch)

dmarc_rua_summary aggregates a rolling window for a patrol. To keep a day-by-day history, a scheduled job can dump the reports themselves:

gwsadm-mcp dmarc-reports --domain example.edu --since 2026-09-20 --until 2026-09-23 > reports.json

• Reads the same RUA mailbox as dmarc_rua_summary (same gmail.readonly scope) for messages that arrived in [--since, --until) (UTC days, Gmail after: / before:), every attachment and every ZIP entry (up to 20 entries and 50 MB decompressed per attachment; anything past that, or an encrypted / corrupt entry, is counted in non_report_attachments).
• Prints one JSON document to stdout: each report whole — org_name, report_id, begin / end (epoch seconds of the reported period), the published policy (p, sp, pct, adkim, aspf) and its records with reason and auth_results. Nothing is aggregated or deduplicated: some reporters split one report across several messages under the same report_id, so deduplicate on content, not on the id.
• fetch_complete is true only when nothing was capped and no message, attachment or record was skipped (message_errors, non_report_attachments, dropped_records).
• Exit 2 for a bad argument or configuration, 1 for an API or auth failure (e.g. the scope was revoked); nothing is written to stdout in either case.
• The output contains sender IPs and header domains. Keep it out of anything published.

Notes

• Every result section reports capped: true when a window exceeded the page budget, or when a probe's fetch errored outright (see event_errors) — partial coverage is never presented as "no findings". The drive scan also reports capped_events (which eventNames were cut short). Narrow hours or raise max_pages for full coverage — on a large tenant, term-time weekdays can produce thousands of change_user_access events/day.
• Google's visibility=shared_externally is relative to the file owner's domain, so with multiple internal_domains a cross-internal-domain grant (e.g. student domain → staff domain) carries it too. External-ness is therefore judged against internal_domains using the grant's target: target_user for named grants, target_domain for domain-scoped grants (e.g. "anyone at partner.edu"; the literal domain "all" means "anyone with the link" and is judged by visibility instead). risky_visibility_events counts only transitions into people_with_link / public_on_the_web (excluding a narrowing from public down to link-only). untargeted_external_transitions is a residual bucket for transitions into shared_externally with no target address or domain to classify — it is not a cross-check for grants missed elsewhere, since domain-scoped grants are already counted above. external_samples / exposure_samples / untargeted_samples hold examples of each.
• Drive events are queried one audit-relevant eventName at a time, so the page budget is not consumed by view/edit noise; an event name rejected by the API degrades into event_errors instead of failing the tool. change_document_visibility and change_document_access_scope report the same transition as simultaneous sibling events on this API — only the latter drives classification (the former is fetched for its acl_events count only), so a domain-scoped grant or a link/public exposure is never double-counted across the two. This also means the former can no longer compensate if the latter's own fetch fails: a change_document_access_scope entry in event_errors sets capped: true for that domain, and its classification counts for the window are a lower bound even though change_document_visibility (and thus acl_events) may show data.
• A failure in one domain degrades only that domain's section ({"error": ...}).
• sets (with ) on a recipient whose mailbox has more than one message under the same Message-ID (mailing-list copy plus a direct CC, a quarantine-release duplicate, …) — the rest of that recipient's fields describe only the first match, not a combined answer. is set alongside it when the mailbox has enough matches that is a lower bound rather than exact (the search does not paginate).

Development

git clone https://github.com/shigechika/gwsadm-mcp.git
cd gwsadm-mcp

# uv
uv sync --dev
uv run pytest -v
uv run ruff check .

# pip
python3 -m venv .venv
.venv/bin/pip install -e . && .venv/bin/pip install pytest ruff
.venv/bin/pytest -v
.venv/bin/ruff check .

Live smoke test

The unit suite never talks to Google, which is what makes it fast — and also what makes it blind to a tool that has stopped returning real data. scripts/smoke_test.py runs every registered tool against the configured tenant and fails on empty, malformed or error answers:

# uses the same config file as the server (GWSADM_CONFIG)
uv run python scripts/smoke_test.py
uv run python scripts/smoke_test.py --only oauth --traceback

• Read-only. Every tool exercised here reads an audit log or a directory snapshot; nothing in Workspace is changed (sign_out_user is skipped). daily_brief_start creates a job inside the process, which expires on its own.
• No payloads in the report. Tool names, statuses and row counts only; server-authored error text is redacted too, since these tools deal in account addresses and document titles throughout.
• Bounded. Every bounding parameter a tool offers is passed explicitly — the defaults (5 pages, 180 days, 200 events) are sized for a human asking once, and are enforced by a test that finds them from the source.
• Nothing tenant-specific in the specs. The account and the document the per-user and per-document tools need are discovered at run time, and skipped when the tenant has none to offer. Two tests keep it that way: one refuses those parameters as literals, the other bans anything address-shaped anywhere in the file, because this repository is public.
• An empty answer passes: no external sharing and no locked accounts is the desired state. What is asserted instead is the envelope — and, where the answer is keyed by domain, that the domain map is not empty, since a config resolving to zero domains would otherwise report every tool as working while auditing nothing.
• CI enforces the cheap half: a tool registered without a probe spec fails the build (tests/test_smoke_probes.py), so adding a tool forces the question "how would we know it works?".
• scripts/smoke_harness.py is the engine and holds no Workspace knowledge: it is kept identical across the servers that share it, so fix engine bugs once and sync the file rather than patching this copy.

Releasing

Releases are automated with release-please. Merging Conventional Commits (feat:, fix:, …) to main keeps a release PR open with the next version and changelog. Merging that PR tags vX.Y.Z and publishes a GitHub Release, whose release: published event triggers the release workflow to build and publish to PyPI and the MCP Registry. release-please owns the version in gwsadm_mcp/__init__.py and server.json (do not bump them by hand).

[!IMPORTANT] The release-please workflow should be given a repository secret RELEASE_PLEASE_TOKEN (a PAT with contents: write + pull-requests: write). The default GITHUB_TOKEN cannot create the Release that triggers the downstream release workflow (GitHub blocks workflow runs triggered by GITHUB_TOKEN), so without the PAT nothing gets published. The workflow falls back to GITHUB_TOKEN when the secret is unset so PR CI keeps working on forks.

License

MIT