Cloud Run MCP

What is Cloud Run MCP about?

Cloud Run MCP provides an MCP server implementation that lets AI‑driven agents and command‑line tools deploy code, list services, fetch logs, and manage Google Cloud projects directly on Cloud Run.

How to use Cloud Run MCP?

1. Local execution – Install Node.js and run the server with npx -y @google-cloud/cloud-run-mcp (or via Docker).
2. Gemini CLI extension – Add the provided gemini-extension.json and GEMINI.md to ~/.gemini/extensions/cloud-run/.
3. Remote server – Deploy the Docker image us-docker.pkg.dev/cloudrun/container/mcp to Cloud Run, protect it with IAM, and proxy locally with gcloud run services proxy.
4. Configuration – Update the MCP client config with the command block (or a url pointing to the proxy).
5. Tool usage – Invoke built‑in tools such as deploy-local-folder, list-services, get-service-log, or use natural‑language prompts like deploy and logs.

Key features of Cloud Run MCP

• Deploy files, folders, or raw content to Cloud Run services.
• List existing services and projects, create new GCP projects, and attach billing.
• Retrieve detailed service information and logs.
• Works as a Gemini CLI extension, a local server, or a remote secure server.
• Supports both Node.js (npx) and Docker execution modes.
• Prompt shortcuts for common tasks (deploy, logs).

Use cases of Cloud Run MCP

• AI‑assisted CI/CD – Let AI agents automatically push code changes to Cloud Run.
• IDE integration – Enable developers using AI‑powered editors (e.g., Cursor, Claude) to deploy with a single command.
• CLI automation – Use Gemini CLI or custom scripts to manage Cloud Run resources across projects.
• Project provisioning – Rapidly create new GCP projects and services from an AI workflow.

FAQ from the Cloud Run MCP

Q: Do I need to install anything besides Node.js? A: No. The npx command pulls the package on demand. For Docker, only Docker is required.

Q: Can I run the server without Google Cloud credentials? A: Local execution requires authenticated gcloud credentials. Remote deployment must be IAM‑protected; unauthenticated access is disabled by default.

Q: How do I set default project, region, or service name? A: Include them in the env section of the MCP configuration (e.g., GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_REGION, DEFAULT_SERVICE_NAME).

Q: Is the remote server publicly accessible? A: No. It is deployed with --no-allow-unauthenticated and accessed via an IAM‑authenticated proxy.

Q: What tools are available when running locally? A: All listed tools (deploy-file-contents, list-services, get-service, get-service-log, deploy-local-files*, deploy-local-folder*, list-projects*, create-project*) are available; those marked with * require local execution.

MCP server to deploy code to Google Cloud Run

Enable MCP-compatible AI agents to deploy apps to Cloud Run.

"mcpServers":{
  "cloud-run": {
    "command": "npx",
    "args": ["-y", "@google-cloud/cloud-run-mcp"]
  }
}

Deploy from Gemini CLI and other AI-powered CLI agents:

Deploy from AI-powered IDEs:

Deploy from AI assistant apps:

Deploy from agent SDKs, like the Google Gen AI SDK or Agent Development Kit.

[!NOTE]
This is the repository of an MCP server to deploy code to Cloud Run, to learn how to host MCP servers on Cloud Run, visit the Cloud Run documentation.

Tools

• deploy-file-contents: Deploys files to Cloud Run by providing their contents directly.
• list-services: Lists Cloud Run services in a given project and region.
• get-service: Gets details for a specific Cloud Run service.
• get-service-log: Gets Logs and Error Messages for a specific Cloud Run service.
• deploy-local-files*: Deploys files from the local file system to a Google Cloud Run service.
• deploy-local-folder*: Deploys a local folder to a Google Cloud Run service.
• list-projects*: Lists available GCP projects.
• create-project*: Creates a new GCP project and attach it to the first available billing account. A project ID can be optionally specified.

* only available when running locally

Prompts

Prompts are natural language commands that can be used to perform common tasks. They are shortcuts for executing tool calls with pre-filled arguments.

• deploy: Deploys the current working directory to Cloud Run. If a service name is not provided, it will use the DEFAULT_SERVICE_NAME environment variable, or the name of the current working directory.
• logs: Gets the logs for a Cloud Run service. If a service name is not provided, it will use the DEFAULT_SERVICE_NAME environment variable, or the name of the current working directory.

Use as a Gemini CLI extension

To install this as a Gemini CLI extension, run the following command:

mkdir -p ~/.gemini/extensions/cloud-run/gemini-extension && \
  curl -s -L https://raw.githubusercontent.com/GoogleCloudPlatform/cloud-run-mcp/main/gemini-extension.json > ~/.gemini/extensions/cloud-run/gemini-extension.json && \
  curl -s -L https://raw.githubusercontent.com/GoogleCloudPlatform/cloud-run-mcp/main/gemini-extension/GEMINI.md > ~/.gemini/extensions/cloud-run/gemini-extension/GEMINI.md

Use as local MCP server

Run the Cloud Run MCP server on your local machine using local Google Cloud credentials. This is best if you are using an AI-assisted IDE (e.g. Cursor) or a desktop AI application (e.g. Claude).

1. Install the Google Cloud SDK and authenticate with your Google account.

2. Log in to your Google Cloud account using the command:

   gcloud auth login
   

3. Set up application credentials using the command:

   gcloud auth application-default login
   

Then configure the MCP server using either Node.js or Docker:

Using Node.js

0. Install Node.js (LTS version recommended).

1. Update the MCP configuration file of your MCP client with the following:

      "cloud-run": {
        "command": "npx",
        "args": ["-y", "@google-cloud/cloud-run-mcp"]
      }
   

2. [Optional] Add default configurations

      "cloud-run": {
         "command": "npx",
         "args": ["-y", "@google-cloud/cloud-run-mcp"],
         "env": {
               "GOOGLE_CLOUD_PROJECT": "PROJECT_NAME",
               "GOOGLE_CLOUD_REGION": "PROJECT_REGION",
               "DEFAULT_SERVICE_NAME": "SERVICE_NAME"
         }
      }
   

Using Docker

See Docker's MCP catalog, or use these manual instructions:

0. Install Docker

1. Update the MCP configuration file of your MCP client with the following:

      "cloud-run": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "GOOGLE_APPLICATION_CREDENTIALS",
          "-v",
          "/local-directory:/local-directory",
          "mcp/cloud-run-mcp:latest"
        ],
        "env": {
          "GOOGLE_APPLICATION_CREDENTIALS": "/Users/slim/.config/gcloud/application_default-credentials.json",
          "DEFAULT_SERVICE_NAME": "SERVICE_NAME"
        }
      }
   

Use as remote MCP server

[!WARNING]
Do not use the remote MCP server without authentication. In the following instructions, we will use IAM authentication to secure the connection to the MCP server from your local machine. This is important to prevent unauthorized access to your Google Cloud resources.

Run the Cloud Run MCP server itself on Cloud Run with connection from your local machine authenticated via IAM. With this option, you will only be able to deploy code to the same Google Cloud project as where the MCP server is running.

1. Install the Google Cloud SDK and authenticate with your Google account.

2. Log in to your Google Cloud account using the command:

   gcloud auth login
   

3. Set your Google Cloud project ID using the command:

   gcloud config set project YOUR_PROJECT_ID
   

4. Deploy the Cloud Run MCP server to Cloud Run:

   gcloud run deploy cloud-run-mcp --image us-docker.pkg.dev/cloudrun/container/mcp --no-allow-unauthenticated
   

   When prompted, pick a region, for example europe-west1.

   Note that the MCP server is not publicly accessible, it requires authentication via IAM.

5. [Optional] Add default configurations

   gcloud run services update cloud-run-mcp --region=REGION --update-env-vars GOOGLE_CLOUD_PROJECT=PROJECT_NAME,GOOGLE_CLOUD_REGION=PROJECT_REGION,DEFAULT_SERVICE_NAME=SERVICE_NAME,SKIP_IAM_CHECK=false
   

6. Run a Cloud Run proxy on your local machine to connect securely using your identity to the remote MCP server running on Cloud Run:

   gcloud run services proxy cloud-run-mcp --port=3000 --region=REGION --project=PROJECT_ID
   

   This will create a local proxy on port 3000 that forwards requests to the remote MCP server and injects your identity.

7. Update the MCP configuration file of your MCP client with the following:

      "cloud-run": {
        "url": "http://localhost:3000/sse"
      }
   
   

   If your MCP client does not support the url attribute, you can use mcp-remote:

      "cloud-run": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "http://localhost:3000/sse"]
      }