Cloud Run MCP Server for Claude Code: Setup & Config

What you can do with Cloud Run in Claude Code

Deploy from an agent and investigate the resulting Cloud Run service without changing integrations.

• Move application source from an agent workflow into a Cloud Run deployment.
• Discover or create Google Cloud projects when operating the server locally.

Before you start: Cloud Run in Claude Code

• Node.js, preferably an LTS release
• Installed Google Cloud SDK
• Google account authentication and application-default credentials
• MCP client configured to start the local package

The command matches the README's recommended local Node configuration, not the bare script from config_hint. Prepare credentials with gcloud auth login followed by gcloud auth application-default login. All three environment entries are optional defaults. A remotely hosted server follows a different authenticated setup and does not expose the local-only tools.

Cloud Run Claude Code configuration

1. Choose Claude Code configuration scope

   For Cloud Run MCP Server, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add Cloud Run MCP Server to Claude Code

   Use the cloud-run-mcp entry below in mcpServers. Keep Cloud Run MCP Server's documented stdio connection fields and your other Claude Code entries.

3. Check Cloud Run MCP Server in Claude Code

   Cloud Run MCP Server: Inspect claude mcp list and /mcp status.

{
  "mcpServers": {
    "cloud-run-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@google-cloud/cloud-run-mcp"
      ],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "<optional project ID used when a request omits it>",
        "GOOGLE_CLOUD_REGION": "<optional deployment region used by default>",
        "DEFAULT_SERVICE_NAME": "<optional fallback name for the Cloud Run service>"
      }
    }
  }
}

claude mcp add-json --scope project 'cloud-run-mcp' '{"type":"stdio","command":"npx","args":["-y","@google-cloud/cloud-run-mcp"],"env":{"GOOGLE_CLOUD_PROJECT":"<optional project ID used when a request omits it>","GOOGLE_CLOUD_REGION":"<optional deployment region used by default>","DEFAULT_SERVICE_NAME":"<optional fallback name for the Cloud Run service>"}}'

Cloud Run tools available to Claude Code

Cloud Run's stored tool list documents 7 tools; compare it with Claude Code's connected tool list, because the stored list is not a live check.

get-service-log

For Cloud Run's get-service-log, review the permission request and arguments in Claude Code before approval.

get-service

For Cloud Run's get-service, review the permission request and arguments in Claude Code before approval.

list-services

For Cloud Run's list-services, review the permission request and arguments in Claude Code before approval.

Discover services within the chosen region and project.

deploy-file-contents

For Cloud Run's deploy-file-contents, review the permission request and arguments in Claude Code before approval.

Publish an application by supplying its files' contents directly.

deploy-local-folder

For Cloud Run's deploy-local-folder, review the permission request and arguments in Claude Code before approval.

Use a source directory for deployment; exposed only by a locally running instance.

list-projects

For Cloud Run's list-projects, review the permission request and arguments in Claude Code before approval.

create-project

For Cloud Run's create-project, review the permission request and arguments in Claude Code before approval.

In local mode, create a project linked to the first available billing account, optionally choosing its ID.

Cloud Run: full stored tool descriptions

Troubleshooting Cloud Run in Claude Code

• If Cloud Run MCP Server fails to start, check npx @google-cloud/cloud-run-mcp (Node.js/npm), the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• Cloud Run MCP Server: check DEFAULT_SERVICE_NAME, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_REGION; keep credentials out of shared .mcp.json.
• Cloud Run MCP Server uses stdio here: Claude Code must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Remote instances cannot deploy outside their own hosting project.
• Known limitation: Folder deployment and project discovery or creation are unavailable in remote mode.
• Known limitation: Remote access needs authentication; host validation is not enabled by default.
• General Claude Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions