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, it never mutates anything.

Features

Planned: dlp_events (Reports rules; requires a Workspace edition with DLP), token_events, admin_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: