gwsadm-mcp: Instructions file for Claude Code

CLAUDE.md

Overview

MCP (Model Context Protocol) server for Google Workspace security auditing. Exposes login_audit (Google-side account locks, suspicious logins), gmail_usage_report (daily Gmail send/receive counts per domain via Reports API customerUsageReports, one date at a time ending yesterday in the API's own UTC-8:00/PST anchor -- requires the separate admin.reports.usage.readonly DWD scope, a DIFFERENT grant from admin.reports.audit.readonly despite both being Reports API), suspended_accounts (current suspended-account snapshot), get_user (one named account's state — suspended/archived/2SV/last login — via users().get, on the same admin.directory.user.readonly scope suspended_accounts uses; a 404 answers found: false, never an error), user_oauth_tokens (one user's third-party OAuth app grants), drive_external_sharing (ACL grants to external targets, new link/public exposure), drive_doc_activity (one document's owner + ACL/lifecycle history via a server-side doc_id filter), shared_drive_membership_changes (shared-drive member add/remove/role history), gmail_message_trace (did a known Message-ID reach specific mailboxes, and where — Gmail API, requires the separate gmail.readonly DWD scope, see its docstring), dmarc_rua_summary (DMARC aggregate/RUA report pass/fail summary and top reject-candidate source IPs, per domain — Gmail API against the domain's configured dmarc_rua_mailbox, shares gmail_message_trace's gmail.readonly DWD scope but reads attachment content, not just metadata), group_delivery_policy (a Google Group's own posting/delivery policy — Groups Settings API, requires the separate apps.groups.settings DWD scope), list_group_members (a Google Group's metadata + member roster — Directory API, requires the separate admin.directory.group.readonly and admin.directory.group.member.readonly DWD scopes), and a daily_brief combining the Reports-based tools, to AI assistants via STDIO transport, built on the official mcp Python SDK's FastMCP. Read-only: the only Admin SDK / Groups Settings / Gmail API methods called anywhere in this package are activities().list (Reports API), customerUsageReports().get() (Reports API, for gmail_usage_report -- same discovery document as activities().list but a DIFFERENT DWD scope), users().list (Directory API, for suspended_accounts), users().get (Directory API, for get_user), tokens().list (Directory API, for user_oauth_tokens), groups().get / members().list (Directory API, for list_group_members), groups().get (Groups Settings API, for group_delivery_policy), messages().list / messages().get (Gmail API, format="metadata" only, for gmail_message_trace), and messages().list / messages().get (format="full") / messages().attachments().get() (Gmail API, for dmarc_rua_summary -- this one DOES read message/attachment content, not just metadata, since a DMARC report's data lives in its attachment) — all read-only; no mutating call exists. The underlying googleapiclient.discovery.build() setup call also fetches Google's discovery document over HTTP, separately from this guarantee.