@google-cloud/cloud-run-mcp

中文文档
1.12.0发布于 2026/11/09Apache-2.0ES Module近 30 天下载 4.1万

Cloud Run MCP deployment tool

原始使用文档
文档目录10 节
  1. Tools
  2. Prompts
  3. Environment Variables
  4. Use as a Gemini CLI extension
  5. Use in MCP Clients
  6. Learn how to configure your MCP client
  7. Set up as local MCP server
  8. Set up as remote MCP server
  9. Using MCP Server with OAuth
  10. Configure MCP Server on Gemini CLI to use OAuth

Cloud Run MCP server and Gemini CLI extension

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

Environment Variables

The Cloud Run MCP server can be configured using the following environment variables:

VariableDescription
GOOGLE_CLOUD_PROJECTThe default project ID to use for Cloud Run services.
GOOGLE_CLOUD_REGIONThe default region to use for Cloud Run services.
DEFAULT_SERVICE_NAMEThe default service name to use for Cloud Run services.
SKIP_IAM_CHECKControls whether to check for IAM permissions for a Cloud Run service. Set to false to enable checks. This is true by default which is a recommended way to make the service public.
ENABLE_HOST_VALIDATIONPrevents DNS Rebinding attacks by validating the Host header. This is disabled by default.
ALLOWED_HOSTSComma-separated list of allowed Host headers (if host validation is enabled). The default value is localhost,127.0.0.1,::1.
OAUTH_ENABLEDEnables OAuth 2.0 Bearer token verification for incoming HTTP/SSE requests when set to true. Disabled by default.
GOOGLE_OAUTH_AUDIENCEExpected OAuth 2.0 token audience (typically your OAuth Client ID). Required when OAUTH_ENABLED=true.

Use as a Gemini CLI extension

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

  1. Install the extension:

    gemini extensions install https://github.com/GoogleCloudPlatform/cloud-run-mcp
    
  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
    

Use in MCP Clients

Learn how to configure your MCP client

Most MCP clients require a configuration file to be created or modified to add the MCP server.

The configuration file syntax can be different across clients. Please refer to the following links for the latest expected syntax:

Once you have identified how to configure your MCP client, select one of these two options to set up the MCP server. We recommend setting up as a local MCP server using Node.js.

Set up 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

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

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

       "cloud-run": {
         "command": "npx",
         "args": ["-y", "@google-cloud/cloud-run-mcp"]
       }
    
  3. [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:

  1. Install Docker

  2. 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"
         }
       }
    

Set up 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"]
       }
    

Using MCP Server with OAuth

Cloud Run MCP server supports OAuth as an authentication mechanism. In order to use OAuth, create the OAuth client, and configure a .env file with the appropriate values pertaining to your OAuth client. A .env.example is provided for reference.

The Cloud Run MCP server works seamlessly with Google Cloud SDK OAuth client. In order to leverage the Google Cloud SDK OAuth client, you can use the .env.gcloud-sdk-oauth file as your .env file as follows:

cp .env.gcloud-sdk-oauth .env
node mcp-server.js

Configure MCP Server on Gemini CLI to use OAuth

When the Cloud Run MCP server is started in the OAuth mode, the MCP client should also be configured to use OAuth. You can setup the MCP server in OAuth mode in the Gemini CLI by using the following JSON in the ~/.gemini/settings.json file:

{
  "mcpServers": {
    "cloud-run": {
      "httpUrl": "http://localhost:3000/mcp",
      "oauth": {
        "enabled": true,
        "clientId": "<OAUTH_CLIENT_ID>",
        "clientSecret": "<OAUTH_CLIENT_SECRET>"
      }
    }
  }
}

Post the configuration changes as shown above, start the Gemini CLI. You should authenticate the Cloud Run MCP server using the following prompt in the Gemini CLI:

/mcp auth cloud-run

This will take you to the authentication page on your browser, wherein you need to sign in using the appropriate gmail id, and accept the terms and conditions. Once the authentication is succcessful, you can come back to the Gemini CLI, and the Cloud Run MCP server will be ready to use.

The Google Cloud Platform Terms of Service (available at https://cloud.google.com/terms/) and the Data Processing and Security Terms (available at https://cloud.google.com/terms/data-processing-terms) do not apply to any component of the Cloud Run MCP Server software.

Cloud Run Skills

We introduce Cloud Run skills to enable AI agents to perform actions on Cloud Run. You can use these skills with Gemini CLI and other agentic AI tools. The skills are available at Cloud Run Skills.

The Cloud Run skills are based on top of gcloud cli for Cloud Run empowering agents to perform all the actions on the Cloud Run using gcloud, as can be performed by the GCP user using gcloud cli.

In order to use Cloud Run skills:

  1. Ensure you have the gcloud CLI installed and authenticated with gcloud auth login and gcloud auth application-default login.
  2. Set your project with gcloud config set project [PROJECT_ID].
  3. Enable the skills on your agentic AI tool. For example, you can enable the skills for Gemini CLI using the following command on your terminal:
gemini skills install https://github.com/GoogleCloudPlatform/cloud-run-mcp.git --path skills/cloud-run
  1. Once the skills are enabled, you can use them to perform actions on Cloud Run. Here are some of the prompts for you to get started:
  • List the Cloud Run services in the project test-gcp-project in the region us-west1.

  • Deploy the folder /home/username/workspace/hello-world as Cloud Run service hello-world to the project test-gcp-project in the region us-west1.

  • Describe the Cloud Run job hello-job in the project test-gcp-project in the region europe-west1.

版本与发布记录

@google-cloud/cloud-run-mcp 共发布 11 个版本,首次发布于 2025/08/13;过去 12 个月发布了 7 个版本。

版本发布日期距今
1.12.0latest2026/11/097 天前
1.11.02026/09/281 个月前
1.10.02026/03/048 个月前
1.9.02026/02/238 个月前
1.8.02026/01/289 个月前
1.7.02026/01/179 个月前

关于 @google-cloud/cloud-run-mcp 的常见问题

@google-cloud/cloud-run-mcp 是什么?

Cloud Run MCP deployment tool

如何安装 @google-cloud/cloud-run-mcp?

在项目目录运行 npm install @google-cloud/cloud-run-mcp,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 cloud-run-mcp,可以用 npx cloud-run-mcp 直接运行。

@google-cloud/cloud-run-mcp 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/google-cloud__cloud-run-mcp 是否存在。

@google-cloud/cloud-run-mcp 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@google-cloud/cloud-run-mcp 可以商用吗?

@google-cloud/cloud-run-mcp 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@google-cloud/cloud-run-mcp 的下载量有多少?

根据 npm 官方下载统计,@google-cloud/cloud-run-mcp 在 2026/10/17 – 2026/11/15 这 30 天内被下载 40,591 次,日均约 1,353 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@google-cloud/cloud-run-mcp 还在维护吗?

最新版本 1.12.0 发布于 2026/11/09(7 天前);至今共发布 11 个版本,其中过去 12 个月发布了 7 个;首次发布于 2025/08/13。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。