Skip to content

t1k:gcloud

FieldValue
Modulet1k-gcloud
Version2.8.51
Effortmedium
Tools—

Keywords: artifact registry, bigquery, cloud build, cloud functions, cloud logging, cloud monitoring, cloud run, cloud sql, cloud storage, cloud storage bucket, compute engine, firestore, gce, gcloud, gcloud iam, gcp, gcp service account, gcs bucket, gke, google cloud, kubernetes engine, pub/sub, vertex ai

/t1k:gcloud
[what to inspect or change, plus project and region]

Operate Google Cloud from Claude through one MCP tool, run_gcloud_command, served by Google’s local @google-cloud/gcloud-mcp server. The tool runs a gcloud command as your own active gcloud account — so the blast radius of a mistake is your IAM role, and the only thing between an agent and projects delete is the deny policy. Treat every command as a real production command, because it is one.

The full history and rationale behind these files is at docs/gcloud-mcp.md in the kit repo.

IntentPath
Server not registered / mcp__gcloud__ tools absentSetup → references/setup-and-auth.md
“what’s running in project X” / inventory / describe / logsInspect
“deploy this to Cloud Run” / GKE / Cloud SQL / any create-update-deleteChange — never skip to the command
“is this command allowed?” / a command was refusedPolicy → references/allow-deny-policy.md
“can I talk to BigQuery/Logging over HTTP instead?”references/remote-servers.md — documented, not wired
A Cloudflare Worker, D1, or R2 questionNot this skill — route to t1k-devops-engineer
“why is my service 500ing” with no gcloud evidence yett1k-debugger first; come back once the question is GCP-shaped

The module is opt-in — it installs nothing until you ask for it:

Terminal window
t1k modules add t1k-gcloud
~/.claude/skills/t1k-gcloud/scripts/install-gcloud-mcp.sh

The installer refuses rather than half-works: no gcloud on PATH, or no ACTIVE gcloud account, is a hard error naming the exact fix command. It then registers the server at local scope (-s local, which the shared gateway later collapses into its single user-scope http entry when the operator opted in) with the pinned package and this module’s deny policy as an absolute -c path. Start a new session to pick the server up; confirm with claude mcp list (expect gcloud connected).

Auth is your ambient gcloud auth login session — this module stores no credential. For least privilege, impersonate a service account instead of using your own identity; both are in references/setup-and-auth.md.

run_gcloud_command takes args as an ARRAY of argv tokens, without the leading gcloud — {"args": ["compute", "instances", "list"]}, not a command string (verified live 2026-09-16; the tool rejects a string, and a leading "gcloud" token errors with Invalid choice: 'gcloud'). Read-only work is always allowed — do it freely, but ask a specific question rather than dumping a project:

  • Inventory: compute instances list, run services list, container clusters list, sql instances list, storage buckets list.
  • Describe one thing: run services describe <svc> --region <r> --format json.
  • Logs: logging read 'severity>=ERROR' --limit 50 --freshness 1h --format json.
  • IAM: projects get-iam-policy <project> --format json, iam service-accounts list.
  • Cost sanity: billing/compute instances list --format 'table(name,zone,machineType)' and a right-sizing read; the cloud-cost door doc cited in references/ops-playbook.md is the gate.

Pass --format json (or --format value(...)) on anything you will reason over. gcloud’s default table output is built for humans and quietly truncates long values.

Any create / update / deploy / delete follows inspect → plan → confirm → act, defined in references/ops-playbook.md. The non-negotiable rules:

  1. Read before write. Describe the current state first and quote it. A deploy that assumed the wrong image tag is a rollback, not a typo.
  2. State the exact command, the project, and the region BEFORE running it, then get explicit confirmation (AskUserQuestion) — unless the brief pre-authorised that specific change.
  3. Preview where the command supports it — --dry-run, a describe of the intended end state, or a diff against the live config. Bulk/destructive work is rules/preview-first-batch.md: smoke a small N, surface it, confirm, then scale.
  4. Never route around the policy. A denied command (references/allow-deny-policy.md) is a decision, not an obstacle: do not re-run it through Bash gcloud, and do not edit the policy file to unblock yourself. Report the denial and let the human change the policy.

Two layers, only the second configurable:

  • Google’s default deny list is ALWAYS enforced and cannot be overridden — ssh-family commands, compute start-iap-tunnel, connect-to-serial-port, interactive, meta. It is a security boundary, not a setting.
  • T1K’s layer lives at config/gcloud-mcp-policy.json as a {"deny": [...]} list and is attached at registration time. It blocks whole command groups (alpha) and the destructive, identity-destroying, and privilege-escalating verbs a Preview agent should never reach for unaided (projects delete, storage rm, iam service-accounts delete, …).

Upstream accepts allow XOR deny, never both — a file with both keys makes the server refuse to start (it logs Configuration can not specify both "allow" and "deny" and exits 1), so claude mcp list shows it disconnected. Full rationale per category, and how a consumer overrides it deliberately, in references/allow-deny-policy.md.

  • Preview software. Google labels this server Preview: “may see breaking changes”, “not an officially supported product”. The package is pinned for that reason; a bump is a reviewed change, never a floating @latest.
  • bunx cold start. The first call of a session may spend 30–60s resolving the package before any gcloud call runs. Not a hang — see references/hard-rules.md before retrying.
  • Absolute policy path. Upstream requires it and enforces it: a relative -c is rejected with Config file path must be absolute and the server exits 1 — it fails closed, never open.
  • One tool. If run_gcloud_command is missing from the tool list, the server is not registered or the session predates registration — registration is per-session, not per-call.

The mechanical steps here are two: run the installer, and run a read-only gcloud command whose output is then reasoned over. Both are single-purpose and stay with the caller by default.

StepAgent
Register the gcloud MCP server, verify with claude mcp listt1k-gcloud-engineer
Read-only inventory / describe / logs / IAM reviewt1k-gcloud-engineer
Create / update / deploy / delete, cost review, policy refusalt1k-gcloud-engineer

routing SSOT: docs/orchestration-rules.md § “Task-Type → Agent Routing”. t1k-gcloud-engineer is a sonnet tier — it is the only role this module adds, and it is on-topic for every row above.

  • references/setup-and-auth.md — install, auth, impersonation, verification, troubleshooting
  • references/allow-deny-policy.md — Google’s default list, T1K’s list, overriding it safely
  • references/ops-playbook.md — inspect → plan → confirm → act, preview-first, cost sanity
  • references/hard-rules.md — the failure shapes and what they actually mean
  • references/remote-servers.md — Google’s HTTP MCP servers, for later