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

Related MCP server: Cloud Run MCP Server

What you get

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:

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

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>:

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

Configuration reference

Environment variables

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

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:

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