grok-mcp-cloudrun

Grok plugin for deploying and managing Google Cloud Run services.

Deploy and manage Cloud Run from Grok using MCP tools, slash commands, and a Cloud Run skill. This repo is a thin wrapper around Google's open-source @google-cloud/cloud-run-mcp — it does not fork or vendor the upstream server.

Not affiliated with Google. See NOTICE for upstream attribution.

See GROK-CHANGES.md for a full list of Grok-specific additions and lessons learned from testing.

---

Table of contents

1. What you get
2. Prerequisites
3. Quick start
4. Installation
5. Quick test (deploy + curl)
6. Daily usage
7. Configuration reference
8. Troubleshooting
9. Project layout
10. Hosted MCP vs local plugin
11. License

---

What you get

Component	What it does
MCP server	Deploy folders, list services, fetch logs via cloud-run__* tools
Skill	cloud-run — MCP-first workflow with gcloud fallback
Slash commands	/deploy and /logs
Hooks	Warns if no GCP project is set; blocks create-project by default

---

Prerequisites

Install and authenticate before anything else.

1. Google Cloud SDK

gcloud auth login
gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID

2. Environment variables

export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
export GOOGLE_CLOUD_REGION=us-central1          # optional, defaults to us-central1
export DEFAULT_SERVICE_NAME=                    # optional, defaults to cwd basename

3. Node.js

Node.js LTS is required for npx to spawn the MCP server.

4. IAM roles

Your account needs permission to deploy and read Cloud Run resources:

Action	Minimum roles
Deploy	roles/run.admin — or roles/run.developer + roles/iam.serviceAccountUser
Logs	roles/logging.viewer + Cloud Run read access
Source upload	roles/storage.admin, roles/artifactregistry.writer (as needed by your build)

5. Verify MCP connectivity

grok mcp doctor cloud-run

Expected output: Found 1 healthy, 0 failing with 8 tools discovered.

---

Quick start

If this repo is already on your machine:

# Install and trust the plugin
grok plugin install /path/to/grok-mcp-cloudrun --trust
grok plugin enable cloud-run

# Confirm everything loaded
grok plugin validate /path/to/grok-mcp-cloudrun
grok inspect

Open Grok and check:

• /plugins — cloud-run is enabled
• /mcps — cloud-run server shows 8 tools
• /skills — cloud-run skill is listed

---

Installation

Choose one path. Do not enable both with the same server name — pick plugin or bare MCP config.

Option A: Plugin (recommended)

Includes skills, slash commands, and safety hooks.

grok plugin install /path/to/grok-mcp-cloudrun --trust
grok plugin enable cloud-run

The --trust flag is required for MCP servers and hooks to activate.

Option B: MCP config only

For personal use without the plugin wrapper:

grok mcp add cloud-run \
  -e GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID \
  -e GOOGLE_CLOUD_REGION=us-central1 \
  -- npx -y @google-cloud/cloud-run-mcp@1.10.0

Or add manually to ~/.grok/config.toml:

[mcp_servers.cloud-run]
command = "npx"
args = ["-y", "@google-cloud/cloud-run-mcp@1.10.0"]
enabled = true
startup_timeout_sec = 60

[mcp_servers.cloud-run.env]
GOOGLE_CLOUD_PROJECT = "${GOOGLE_CLOUD_PROJECT}"
GOOGLE_CLOUD_REGION  = "${GOOGLE_CLOUD_REGION:-us-central1}"
DEFAULT_SERVICE_NAME = "${DEFAULT_SERVICE_NAME:-}"

[mcp_servers.cloud-run.tool_timeouts]
deploy-local-folder = 600

---

Quick test (deploy + curl)

End-to-end smoke test: clone a sample app, deploy it from Grok, then hit it with curl.

Step 1 — Clone the sample

git clone https://github.com/GoogleCloudPlatform/cloud-run-mcp.git /tmp/cloud-run-mcp
cd /tmp/cloud-run-mcp/example-sources-to-deploy/nodejs

Upstream also provides golang, java, and python samples in the same directory.

Step 2 — Deploy from Grok

In a Grok session (with this directory as your working folder):

/deploy hello-test

Grok calls cloud-run__deploy-local-folder and returns a public HTTPS URL when the deploy finishes. First deploy can take several minutes (Cloud Build + container push).

Step 3 — Verify with curl

Use the URL from the deploy response, or look it up with gcloud:

# Option A: URL from /deploy output
curl -sS https://hello-test-XXXXXXXX-uc.a.run.app/

# Option B: resolve URL via gcloud
SERVICE_URL=$(gcloud run services describe hello-test \
  --region="${GOOGLE_CLOUD_REGION:-us-central1}" \
  --project="${GOOGLE_CLOUD_PROJECT}" \
  --format='value(status.url)')

curl -sS "$SERVICE_URL/"

Expected response:

Hello from Node.js on Cloud Run!

Health check:

curl -sS -o /dev/null -w "HTTP %{http_code}\n" "$SERVICE_URL/health"

Expected: HTTP 200

Step 4 — Check logs

Back in Grok:

/logs hello-test

Or from the shell:

gcloud run services logs read hello-test \
  --region="${GOOGLE_CLOUD_REGION:-us-central1}" \
  --limit=20

Step 5 — Clean up (optional)

gcloud run services delete hello-test \
  --region="${GOOGLE_CLOUD_REGION:-us-central1}" \
  --quiet

---

Daily usage

Slash commands

Command	Action
/deploy	Deploy cwd; service name = directory basename
/deploy my-api	Deploy cwd as my-api
/logs	Logs for default service name
/logs my-api	Logs for my-api

Natural language prompts

• "List Cloud Run services in my-project region us-central1"
• "Deploy the current folder to Cloud Run"
• "Get the URL for service hello-test"
• "Show me recent errors in Cloud Run logs for my-api"

MCP tools

Grok namespaces tools as cloud-run__<tool>:

Tool	Purpose
cloud-run__deploy-local-folder	Deploy cwd to Cloud Run
cloud-run__deploy-file-contents	Deploy files by content (remote mode)
cloud-run__list-services	List services in project/region
cloud-run__get-service	Service details and public URL
cloud-run__get-service-log	Recent logs and errors
cloud-run__list-projects	List GCP projects
cloud-run__create-project	Create project (blocked by default hook)

Discover tools at runtime with search_tool, then call with use_tool.

---

Configuration reference

Environment variables

Variable	Default	Description
GOOGLE_CLOUD_PROJECT	—	GCP project for all operations
GOOGLE_CLOUD_REGION	us-central1	Cloud Run region
DEFAULT_SERVICE_NAME	cwd basename	Default name for /deploy and /logs
SKIP_IAM_CHECK	true (upstream)	When true, new services may be publicly accessible
CONFIRM_CLOUD_RUN_CREATE_PROJECT	unset	Set to 1 to allow create-project (hook blocks it otherwise)
CONFIRM_CLOUD_RUN_PROD_DEPLOY	unset	Set to 1 to deploy when project ID looks like production

Safety hooks

The plugin ships hooks/hooks.json:

• SessionStart — warns if neither GOOGLE_CLOUD_PROJECT nor a gcloud default project is set; warns if ADC is missing
• PreToolUse — blocks cloud-run__create-project unless CONFIRM_CLOUD_RUN_CREATE_PROJECT=1
• PreToolUse — blocks deploy tools to production-like projects unless CONFIRM_CLOUD_RUN_PROD_DEPLOY=1

Timeouts

Cold npx downloads can exceed the default 30s startup timeout. This repo's config uses:

• startup_timeout_sec = 60
• tool_timeouts.deploy-local-folder = 600 (10 min for first deploy)

---

Troubleshooting

Symptom	Fix
grok mcp doctor cloud-run fails	gcloud auth application-default login
MCP starts but deploy fails with auth error	Re-run ADC login; confirm GOOGLE_CLOUD_PROJECT
Cold start / connection timeout	Set startup_timeout_sec = 60 in config
Deploy hangs or times out	Set tool_timeouts = { deploy-local-folder = 600 }
Permission denied on deploy	Check IAM roles in Prerequisites
Plugin MCP shows blocked	Reinstall with grok plugin install ... --trust
Plugin installed but tools missing	grok plugin enable cloud-run
curl returns 403	Service may not be public; check IAM or set SKIP_IAM_CHECK=false and add allUsers invoker binding
curl connection refused right after deploy	Wait 30–60s for the new revision to become ready, then retry

Diagnostic commands

./scripts/verify-setup.sh          # full Phase 3 checklist
grok mcp doctor cloud-run          # MCP health
grok plugin validate .             # plugin manifest
grok inspect                       # skills, commands, hooks, MCP inventory
grok plugin list                   # installed plugins
gcloud auth application-default print-access-token  # confirm ADC

Marketplace

Install from GitHub:

grok plugin install gprot42/grok-mcp-cloudrun --trust
grok plugin enable cloud-run

To submit to the official xAI marketplace, see MARKETPLACE.md.

---

Project layout

grok-mcp-cloudrun/
├── .mcp.json                  # MCP server config (Grok primary)
├── .claude-plugin/plugin.json # Claude-ecosystem compat
├── .grok-plugin/plugin.json   # Marketplace manifest
├── plugin.json                # Plugin metadata
├── commands/
│   ├── deploy.md              # /deploy slash command
│   └── logs.md                # /logs slash command
├── hooks/hooks.json           # SessionStart + PreToolUse safety
├── skills/cloud-run/SKILL.md  # MCP-first Cloud Run workflow
├── LICENSE                    # Apache 2.0 (upstream)
├── NOTICE                     # Upstream attribution
└── README.md                  # This guide

---

Hosted MCP vs local plugin

This plugin runs the MCP server locally via stdio (npx @google-cloud/cloud-run-mcp). That is what powers /deploy, which calls cloud-run__deploy-local-folder on your current working directory.

If you deploy the upstream MCP server itself to Cloud Run, it behaves differently:

	Local plugin (this repo)	Hosted on Cloud Run
Transport	stdio via npx	POST /mcp or GET /sse
/deploy (local folder)	Works	Not available
Deploy by file contents	Yes	Yes
Browser at service URL	N/A	Cannot GET / (expected — no web UI)

To verify a hosted MCP deployment, send an MCP initialize request to /mcp (see GROK-CHANGES.md).

For Grok day-to-day use, install this plugin — do not point Grok at a public Cloud Run URL without IAM authentication.

---

License

Apache License 2.0. See LICENSE and NOTICE.

Upstream MCP server: GoogleCloudPlatform/cloud-run-mcp · npm: @google-cloud/cloud-run-mcp@1.10.0