GAM Server

A high-performance, secure, memory-safe Model Context Protocol (MCP) server that implements Google Workspace administrative controls (Directory, Gmail, Drive, Sheets) via Domain-Wide Delegation (DWD) service account impersonation.

Designed as a modern TypeScript alternative to traditional GAM scripts, this server provides a structured, schema-validated toolset that integrates with any Model Context Protocol host (such as Antigravity or Claude Desktop).

---

Core Architectural Features

• Resilient Rate-Limiting: API requests are wrapped in exponential backoff with fractional randomized jitter. The retry classifier distinguishes retryable (429, 5xx, 403/quotaExceeded, network ECONNRESET/ETIMEDOUT/etc.) from non-retryable errors (400, 403/forbidden, 403/insufficientPermissions), and honors Retry-After headers when the server provides one.
• Stream-to-Disk Operations: StreamDiskWriter pipes large search and audit responses line-by-line directly to local files at 0600 permissions, bypassing standard V8 heap limits to prevent Node.js Out-Of-Memory (OOM) crashes.
• Concurrency-Limitation Gates: A strict write-concurrency queue limited to maximum 5 active operations for Directory mutations, and 10 concurrent Drive audit list pages.
• Token-Scrubbing Filter: Globally intercepts stdout and stderr to mask access tokens (ya29.*), refresh tokens (1//0*), ID tokens (eyJ*.*.*), and PEM private key blocks before any bytes are flushed. Idempotent.
• POSIX Security Guard: Validates service account key file permissions on startup, emitting a high-visibility security warning if the key is world- or group-accessible. Called exactly once at startup.
• Path Allowlist: All tool I/O paths (audit outputs, CSV imports) are resolved under GAM_MCP_OUTPUT_DIR (or cwd if unset). Paths that escape the root are rejected, as are any paths whose ancestry contains a symlink.
• CSV Injection Defense: Spreadsheet-bound output prefixes leading =, +, -, @, \t, \r with a single quote per OWASP guidance, preventing formula injection when audits are opened in Excel or Sheets.
• JWT Client Cache: DWD JWT instances are cached per (subject, scopes) so the underlying google-auth-library access-token cache is reused across many calls within a single audit.
• Multi-line CSV Reader: The Sheets exporter correctly joins records that span multiple physical lines (RFC 4180 §2.6).
• Structured Logging: A stderr-only logger emits human-readable text in test mode and single-line JSON in prod mode (set via NODE_ENV or GAM_MCP_ENV). Log level is gated via --log-level / GAM_MCP_LOG_LEVEL.

---

Tool Catalog (13 Administrative Tools)

Directory & Group Management

• gam_admin_create_user: Creates user accounts. password is optional — if omitted, a cryptographically secure 32-character base64url password (~192 bits of entropy) is generated and returned ONCE in the response.
• gam_admin_update_ou: Moves a user or re-parents an OU. Requires explicit targetType: 'user' | 'ou' (no auto-detection from @).
• gam_admin_sync_group_members: Computes membership diffs and syncs concurrently up to the 5-concurrency write limit. If a group's membership exceeds the MAX_PAGES_LIMIT read cap, the diff would be computed against partial membership: a dry-run returns truncated: true with a warning, and a real sync is refused to avoid a destructive partial sync.
• gam_admin_print_users: Paginated user listing (up to MAX_PAGES_LIMIT pages) in CSV or JSON.
• gam_admin_print_groups: Paginated group listing in CSV or JSON.
• gam_admin_print_group_members: Paginated active-member listing in CSV or JSON.

Gmail Compliance & Mail Auditing

• gam_gmail_search_messages: Searches a mailbox and returns metadata + snippets of the first N results in CSV or JSON.
• gam_gmail_get_message: Fetches details for a single email, decoding base64url MIME parts recursively (depth-capped at 20).
• gam_gmail_bulk_delete: Batch deletes emails matching a query in chunks of 1000 IDs (Gmail's API limit). Default dry-run shows up to 15 sample previews. When more messages match than can be enumerated within the MAX_PAGES_LIMIT page cap, the response sets truncated: true and the message instructs you to re-run (or narrow the query) to delete the remainder.

Drive Security Auditing

• gam_drive_list_files: Lists file metadata. Accepts corpora: 'user' | 'domain' | 'drive' | 'allDrives' to widen the search scope (use allDrives for Shared Drives).
• gam_drive_audit_permissions: Memory-safe permission audit. Streams flattened rows to a file under GAM_MCP_OUTPUT_DIR with the inherited-ancestry cache active across the run. Also accepts corpora.

Sheets & Reports

• gam_export_audit_to_sheets: Streams a local CSV (which MUST live under GAM_MCP_OUTPUT_DIR) to a Sheet tab in safe 2000-row chunks. Auto-creates missing tabs.
• gam_read_admin_sheet: Reads a worksheet range to feed targeting data back into administrative automation runs.

Note: Gmail, Drive, and Sheets tools no longer accept adminUserEmail — the DWD impersonation subject is always the named mailbox/Drive/Sheet owner (userEmail).

---

Google Workspace Setup (Domain-Wide Delegation)

To authorize this service account, a Google Workspace Super-Admin must configure Domain-Wide Delegation (DWD) inside the Google Workspace Admin Console.

1. Create a Service Account in GCP

1. Go to the Google Cloud Console.
2. Create or select a project (e.g., gam-mcp).
3. Enable the following APIs:
   • Admin SDK API (admin.googleapis.com)
   • Gmail API (gmail.googleapis.com)
   • Google Drive API (drive.googleapis.com)
   • Google Sheets API (sheets.googleapis.com)
4. Navigate to IAM & Admin > Service Accounts and create a Service Account (e.g., gam-mcp-sa).
5. Generate and download a JSON credentials key. Save it securely.
6. Set secure POSIX file permissions:

   chmod 0600 ~/secrets/oauth2service.json
   

7. Note the Client ID (Unique ID) of the service account.

2. Configure Domain-Wide Delegation (DWD)

1. Log into the Google Workspace Admin Console as a Super Admin.
2. Go to Security > Access and data control > API controls.
3. Under Domain-wide delegation, click Manage Domain Wide Delegation.
4. Click Add new, enter the Client ID, and paste these OAuth scopes:

   https://www.googleapis.com/auth/admin.directory.user,
   https://www.googleapis.com/auth/admin.directory.group,
   https://www.googleapis.com/auth/admin.directory.group.member,
   https://www.googleapis.com/auth/admin.directory.orgunit,
   https://www.googleapis.com/auth/drive.readonly,
   https://www.googleapis.com/auth/gmail.readonly,
   https://mail.google.com/,
   https://www.googleapis.com/auth/spreadsheets,
   https://www.googleapis.com/auth/spreadsheets.readonly
   

   (https://mail.google.com/ is only required for gam_gmail_bulk_delete.)
5. Save the delegation.

---

Installation & Local Execution

Requires Node.js 20+ LTS (enforced via package.json engines).

cd gam-mcp
npm install
npm run build
npm run test          # unit + integration

---

Configuration

The server resolves settings in this precedence order (highest wins):

1. CLI flags (see below)
2. Environment variables
3. Config file (--config <path>)
4. Built-in defaults

CLI flags

gam-mcp-server [options] [credentials.json]

OPTIONS:
  -c, --credentials <path>   Service-account JSON key file.
      --config <path>        Path to a key=value (or key: value) config file.
      --log-level <level>    error | warn | info | debug
      --read-only            Block all mutating tool invocations.
      --dry-run              Treat mutating tools as dry-runs by default.
  -h, --help                 Show help and exit.
  -v, --version              Show version and exit.

Environment variables

Variable	Purpose
GAM_MCP_CREDENTIALS	Path to the service-account JSON key.
GOOGLE_APPLICATION_CREDENTIALS	Same, but standard GCP env var.
GAM_MCP_CONFIG	Path to a config file (same format as --config).
GAM_MCP_LOG_LEVEL	error | warn | info | debug
GAM_MCP_READ_ONLY	1/true/yes to enable read-only mode.
GAM_MCP_OUTPUT_DIR	Allowlist root for tool I/O. Defaults to cwd.
GAM_MCP_ENV / NODE_ENV	test (default, text logs) or prod (JSON logs).

A template is provided in .env.example.

Config file format

Lines are key = value or key: value. # and ; introduce comments.

credentials = /Users/me/secrets/oauth2service.json
log_level   = info
read_only   = false
output_dir  = /Users/me/gam-mcp-audits

---

Connecting to an MCP Host

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "gam-mcp": {
      "command": "node",
      "args": [
        "/Users/yourname/src/gam-mcp/build/index.js",
        "--log-level", "info"
      ],
      "env": {
        "GAM_MCP_CREDENTIALS": "/Users/yourname/secrets/oauth2service.json",
        "GAM_MCP_OUTPUT_DIR": "/Users/yourname/gam-mcp-audits"
      }
    }
  }
}

Antigravity

Register the server inside your Antigravity MCP registry, ensuring the absolute path to build/index.js is correct.

---

Security & Data Safety Standards

• Read-Only Command Gate: When enabled (via --read-only or GAM_MCP_READ_ONLY), all mutating operations are blocked at the executor level. Dry-runs still proceed.
• Fail-Safe Dry-Runs: All mutating tools default to dryRun: true. Bulk delete additionally surfaces 15 sample previews on dry-run.
• Stderr-Only Logging: The MCP stdio transport requires a pristine stdout. The logger writes ONLY to stderr; stdout is reserved for JSON-RPC.
• Token Scrubbing: Every byte written to stdout/stderr is scanned for known token patterns and masked.
• Output Path Allowlist: Audit writes and CSV imports cannot escape GAM_MCP_OUTPUT_DIR. Symlink-bearing paths are rejected. Files are created with mode 0600.
• Closed-By-Default Error Policy: Errors are returned to MCP callers as text content with isError: true; full stack traces (including cause chains) go to stderr at debug/warn levels.

---

Project files

File	Purpose
AGENT.md	Original developer specification (historical roadmap).
README.md	This file (operational reference).
task.md	Live status tracker.
implementation_plan.md	Architectural design notes.
walkthrough.md	Verification log per release.
.env.example	Environment template.

---

License

MIT.