skills Cloud Run MCP 使用指南：通过远程 MCP 服务器让 Agent 部署、管理与监控 Serverless 应用-迪斯科星球

skills Cloud Run MCP 使用指南：通过远程 MCP 服务器让 Agent 部署、管理与监控 Serverless 应用

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

本文以 Cloud Run MCP Usage 参考文档为核心，讲解cloud-run-basics技能所配套的 Cloud Run 远程 MCP（Model Context Protocol）服务器：它提供哪些工具（get_service、list_services、三种deploy_service_from_*部署工具）、如何完成连接配置，以及 Agent 可以借此自动化哪些运维场景。文中同时结合父技能 SKILL.md 中的 gcloud 命令体系与 IAM 前置要求，把每个 MCP 工具映射到等价的手动 CLI 操作，形成“Agent 工具调用 ↔ 人工命令执行”的双向对照。

一、MCP 参考文档在 cloud-run-basics 技能中的定位

在 google/skills 仓库中，Cloud Run 相关能力被组织为一个完整的 Agent 技能（Agent Skill），其元数据定义于 skills/cloud/cloud-run-basics/SKILL.md 的 frontmatter：

技能名：cloud-run-basics
分类：Serverless
适用场景描述：管理 Cloud Run 的 services、jobs 与 worker pools——即响应 HTTP 请求的应用（services）、事件触发或定时运行的任务（jobs）、以及常驻的拉取式后台处理（worker pools，如 Kafka 消费者、Pub/Sub 拉取队列、RabbitMQ 消费者）。

该技能的 Reference Directory 列出了七份参考文档，覆盖了与 Cloud Run 交互的全部主流方式：

参考文档	交互方式
core-concepts.md	Services / Jobs / Worker pools 资源模型与自动扩缩行为
cli-usage.md	`gcloud run`部署与管理命令
client-library-usage.md	Google Cloud 客户端库
mcp-usage.md	Cloud Run 远程 MCP 服务器（本文主题）
iac-usage.md	Terraform（IaC）示例
iam-security.md	角色、服务身份、入站/出站控制
networking.md	网络最佳实践与成本优化

也就是说，MCP 是并列于 CLI、客户端库、Terraform 的第四种操作入口，其面向的使用者是 AI Agent 而非人类开发者：Agent 通过标准 MCP 协议直接调用工具函数，而不必拼装并执行 shell 命令。该技能可通过仓库 README.md 给出的方式安装：

npx skills add google/skills

安装时可选择仅安装cloud-run-basics这一个技能。

二、Cloud Run MCP 服务器提供的工具

根据 mcp-usage.md，Cloud Run 由一个远程 MCP 服务器提供支持，该服务器让 Agent 能够部署、管理和监控 Serverless 应用。文档明确列出其通常包含的五类工具：

MCP 工具	功能	等价 gcloud 操作（对照 SKILL.md）
`get_service`	获取某个 Cloud Run 服务的详细信息，如服务 URI 和本次部署是否成功	`gcloud run services describe SERVICE_NAME`
`list_services`	列出指定 Google Cloud 项目与区域内的全部 Cloud Run 服务	`gcloud run services list`
`deploy_service_from_image`	将来自 Artifact Registry 或 Docker Hub 的容器镜像部署为 Cloud Run 服务	`gcloud run deploy SERVICE_NAME --image IMAGE_URL`
`deploy_service_from_archive`	直接从一个自包含的源码压缩包（`.tar.gz`）部署服务，跳过容器镜像构建步骤以加快部署；压缩包必须包含全部依赖	对应`--no-build`（Preview）免构建思路
`deploy_service_from_file_contents`	直接从本地源文件内容部署服务，源码内嵌在请求中，适合 Python、Node.js 等脚本语言，是快速测试与开发反馈循环的理想路径；因跳过构建步骤，需在源文件中包含所有必要依赖	介于`--source .`与`--no-build`之间

2.1 三个部署工具的设计差异

三个deploy_service_from_*工具体现了不同的“部署输入形态”，理解它们与 SKILL.md 中 gcloud 部署方式的对应关系，能帮助你判断何时该用 MCP、何时该回退到 CLI：

（1）deploy_service_from_image：镜像即交付物与gcloud run deploy SERVICE_NAME --image IMAGE_URL --region us-central1等价（见 SKILL.md）。SKILL.md 对镜像源的说明同样适用于该工具：可直接使用存放在 Artifact Registry 或 Docker Hub 中的镜像；由于 Docker Hub 镜像在 Artifact Registry 中最多仅缓存一小时，Google 推荐优先使用 Artifact Registry；其他公共/私有仓库（JFrog Artifactory、Nexus、GitHub Container Registry 等）需先配置 Artifact Registry 远程仓库。镜像引用格式形如us-docker.pkg.dev/cloudrun/container/hello:latest，其中 Artifact Registry 仓库名需已存在。

（2）deploy_service_from_archive：跳过构建的归档部署文档强调两个约束：其一，压缩包必须是.tar.gz且自包含；其二，必须包含所有依赖——因为该路径直接部署制品、绕过镜像构建。这与 SKILL.md 中 “Deploy from source without build (Preview)” 的gcloud beta run deploy ... --no-build机制是同一思路（见 SKILL.md），后者要求显式指定--base-image（运行时基础镜像，如us-central1-docker.pkg.dev/serverless-runtimes/google-24-full/runtimes/nodejs24，或部署预编译二进制时使用的osonly24OS-only 镜像）以及--command/--args。

（3）deploy_service_from_file_contents：面向快速迭代的源码内嵌部署与前两者不同，此工具把源代码直接嵌在 MCP 请求里，因此特别适合 Python、Node.js 这类“源码即交付”的脚本语言场景，用于快速测试和开发反馈循环。文档同样提醒：由于跳过构建步骤，所有依赖必须写进源文件内。需要注意，SKILL.md 在故障排查章节特别指出（见 SKILL.md）：若采用免构建路径遇到 Node/Python 原生依赖（native dependency）错误，应改回--source .（Buildpacks）让构建系统为 Linux 正确编译原生扩展——这条经验对使用上述两个免构建 MCP 工具的 Agent 同样成立。

2.2 所有部署路径的共同硬约束

无论走哪条部署通道，SKILL.md 都标注了一条关键规则（见 SKILL.md）：

部署的代码必须监听0.0.0.0（而非127.0.0.1），并使用注入的$PORT环境变量（默认 8080），否则实例将在启动时崩溃。

当 Agent 通过deploy_service_from_file_contents生成并嵌入 Python/Node.js 源码时，这条约束尤其容易踩坑，建议在提示词中显式声明。

三、连接与配置：接入 Cloud Run 远程 MCP 服务器

mcp-usage.md 给出的接入流程共三步：

在目标 Google Cloud 项目中启用 Cloud Run API（对应 SKILL.md 前置命令为gcloud services enable run.googleapis.com cloudbuild.googleapis.com --quiet，即同时启用 Cloud Run Admin API 与 Cloud Build API，见 SKILL.md）；
使用 Gemini CLI 扩展（Gemini CLI extension）配置 Agent 的 MCP 连接；
按照 Google Cloud 官方的 “Setting up Cloud Run MCP” 指南完成其余配置细节。

此外，文档还指出一个可替代选项：使用 GoogleCloudPlatform 开源的本地 Cloud Run MCP 服务器，它在本机运行，适合不便接入远程服务器的开发/测试环境。

3.1 本仓库中 MCP 连接的标准配置形态

从源码结构看，本仓库统一使用 Agent Plugins / Gemini 扩展的声明式格式描述 MCP 连接，可参考 plugins/cloud/google-cloud-developer/mcp.json：

{ "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", "mcpServers": { "developer-knowledge": { "type": "streamable-http", "url": "https://developerknowledge.googleapis.com/mcp" } } }

以及 plugins/cloud/google-cloud-developer/gemini-extension.json 中对应的 Gemini CLI 扩展写法：

{ "mcpServers": { "developer-knowledge": { "httpUrl": "https://developerknowledge.googleapis.com/mcp", "authProviderType": "google_credentials" } } }

需要说明：该插件（元数据见 plugins/cloud/google-cloud-developer/plugin.json，版本 1.1.1）捆绑的是 Developer Knowledge MCP 服务器，而非 Cloud Run MCP 服务器；但两者展示了同一套配置范式——mcpServers下按服务器名注册streamable-http类型的远程端点，并以google_credentials作为认证提供者。配置 Cloud Run 远程 MCP 服务器时可参照此形态，具体端点以官方指南为准。SKILL.md 末尾也提示：若需要的产品信息在上述参考文档中找不到，可调用 Developer Knowledge MCP 服务器的search_documents工具检索官方文档（见 SKILL.md）。

3.2 Agent 调用 MCP 工具所需的 IAM 角色

文档正文未单列角色清单，但与 MCP 部署操作等价的gcloud run deploy在 SKILL.md 中要求以下角色，Agent 执行账号（或其背后的人类身份）应满足同样前提：

项目级 Cloud Run Admin（roles/run.admin）
项目级 Cloud Run Source Developer（roles/run.sourceDeveloper）
服务身份上的 Service Account User（roles/iam.serviceAccountUser）
项目级 Logs Viewer（roles/logging.viewer）

若涉及构建，还需为 Cloud Build 服务账号授予roles/run.builder：

gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \ --role=roles/run.builder \ --quiet

四、Agent 可自动化的运维场景

mcp-usage.md 的 “Supported Operations” 一节列出了三类典型场景。结合 SKILL.md 的手动等价命令，可以具体化如下：

（1）自动化新版本（revision）滚动发布Agent 循环调用deploy_service_from_*部署新修订版本，再通过get_service核对服务 URI 与部署成功状态，形成“部署 → 验证”闭环，无需人工执行gcloud run deploy与gcloud run services describe。

（2）排查部署失败：检查日志与状态当部署失败时，Agent 可借助 MCP 工具检查服务状态并拉取日志。SKILL.md 给出了对应的故障排查手册（见 SKILL.md），可直接作为 Agent 的系统性排障剧本：

IAM/权限错误：查阅 iam-security.md；
启动崩溃 / 健康检查失败：立即用gcloud logging read "resource.labels.service_name=SERVICE_NAME" --limit=20拉取日志定位运行时错误；
Node/Python 原生依赖错误：从免构建路径切回--source .（Buildpacks）。

（3）管理定时任务并校验执行历史SKILL.md 的 Job 章节（见 SKILL.md）说明了 Cloud Run Jobs 的创建与执行方式：

gcloud run jobs create JOB_NAME --image IMAGE_URL OPTIONS --quiet gcloud run jobs execute JOB_NAME --quiet gcloud run jobs execute JOB_NAME --wait --region=REGION --quiet

Agent 通过 MCP 管理这些定时任务时，可参照的 Job 关键参数（均出自 SKILL.md）包括：

参数	取值与默认值
`--tasks`	≥1 的整数，默认 1，最大 10000；每个任务注入`CLOUD_RUN_TASK_INDEX`（0 到任务数减 1）与`CLOUD_RUN_TASK_COUNT`环境变量
`--max-retries`	失败任务重试次数，0–10，默认 3；任一任务重试超限则整个 Job 标记失败
`--task-timeout`	时长格式（如`2s`），默认 10 分钟，最大 168 小时（7 天）；GPU 任务最长 1 小时
`--parallelism`	最大并行任务数，默认尽快全部并行启动
`--execute-now`	创建后立即启动一次执行，等价于 create + execute

Worker pool 场景（gcloud run worker-pools deploy WORKER_POOL_NAME --image IMAGE_URL/--source .）也可纳入同一 MCP 工作流，镜像同样支持 tag 或精确 digest（@sha256:...）两种引用方式（见 SKILL.md）。

五、适用前提与局限小结

前提：项目内已启用 Cloud Run API（及 Cloud Build API，若涉及构建）；调用方具备前述 IAM 角色；MCP 连接按官方指南配置完成。
部署约束：免构建类工具（archive / file_contents）要求依赖完全内嵌；含原生扩展的 Node/Python 项目建议走带构建路径。
两条路线选择：远程 MCP 服务器由 Cloud Run 官方提供，无需在本机安装任何 MCP 组件；若处于离线开发环境或需要更细粒度控制，文档给出的开源本地 Cloud Run MCP 服务器是官方认可的替代方案。
信息兜底：对于参考文档未覆盖的产品细节，SKILL.md 建议调用 Developer Knowledge MCP 的search_documents工具检索官方文档，避免 Agent 基于过时知识作答。

六、延伸阅读（仓库内相对路径）

参考文档主体：skills/cloud/cloud-run-basics/references/mcp-usage.md
父技能主文档（资源模型、部署命令、Job/Worker pool、故障排查）：skills/cloud/cloud-run-basics/SKILL.md
CLI 详解：skills/cloud/cloud-run-basics/references/cli-usage.md
Terraform 配置：skills/cloud/cloud-run-basics/references/iac-usage.md
IAM 与安全：skills/cloud/cloud-run-basics/references/iam-security.md
网络与成本优化：skills/cloud/cloud-run-basics/references/networking.md
MCP 插件配置范式：plugins/cloud/google-cloud-developer/mcp.json、plugins/cloud/google-cloud-developer/gemini-extension.json

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析