t1k:gcloud
| Field | Value |
|---|---|
| Module | t1k-gcloud |
| Version | 2.8.51 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/t1k:gcloud[what to inspect or change, plus project and region]T1K Google Cloud
Section titled “T1K Google Cloud”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.
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
Server not registered / mcp__gcloud__ tools absent | Setup → references/setup-and-auth.md |
| “what’s running in project X” / inventory / describe / logs | Inspect |
| “deploy this to Cloud Run” / GKE / Cloud SQL / any create-update-delete | Change — never skip to the command |
| “is this command allowed?” / a command was refused | Policy → 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 question | Not this skill — route to t1k-devops-engineer |
| “why is my service 500ing” with no gcloud evidence yet | t1k-debugger first; come back once the question is GCP-shaped |
The module is opt-in — it installs nothing until you ask for it:
t1k modules add t1k-gcloud~/.claude/skills/t1k-gcloud/scripts/install-gcloud-mcp.shThe 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.
Inspect
Section titled “Inspect”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 inreferences/ops-playbook.mdis 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.
Change
Section titled “Change”Any create / update / deploy / delete follows inspect → plan → confirm → act, defined in
references/ops-playbook.md. The non-negotiable rules:
- 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.
- 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. - Preview where the command supports it —
--dry-run, adescribeof the intended end state, or a diff against the live config. Bulk/destructive work isrules/preview-first-batch.md: smoke a small N, surface it, confirm, then scale. - 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 Bashgcloud, and do not edit the policy file to unblock yourself. Report the denial and let the human change the policy.
Policy
Section titled “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.jsonas 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.
Notes that bite
Section titled “Notes that bite”- 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. bunxcold start. The first call of a session may spend 30–60s resolving the package before any gcloud call runs. Not a hang — seereferences/hard-rules.mdbefore retrying.- Absolute policy path. Upstream requires it and enforces it: a relative
-cis rejected withConfig file path must be absoluteand the server exits 1 — it fails closed, never open. - One tool. If
run_gcloud_commandis missing from the tool list, the server is not registered or the session predates registration — registration is per-session, not per-call.
Executed by
Section titled “Executed by”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.
| Step | Agent |
|---|---|
Register the gcloud MCP server, verify with claude mcp list | t1k-gcloud-engineer |
| Read-only inventory / describe / logs / IAM review | t1k-gcloud-engineer |
| Create / update / deploy / delete, cost review, policy refusal | t1k-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
Section titled “References”references/setup-and-auth.md— install, auth, impersonation, verification, troubleshootingreferences/allow-deny-policy.md— Google’s default list, T1K’s list, overriding it safelyreferences/ops-playbook.md— inspect → plan → confirm → act, preview-first, cost sanityreferences/hard-rules.md— the failure shapes and what they actually meanreferences/remote-servers.md— Google’s HTTP MCP servers, for later