借助 MCP 远程驱动 gcloudskills 仓库 Cloud CLI 远程 MCP 服务器实战指南【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本指南围绕skills仓库中 gcloud 技能包 的 MCP 使用文档系统讲解如何通过 Cloud CLI 远程 MCP 服务器run_gcloud_command让 AI Agent 以结构化工具调用的方式安全执行gcloud命令涵盖端点与工具概览、mcp_config.json客户端配置、API 启用与 IAM 前置条件、参数语义含 API 宿主项目与资源项目的关键区分、响应结构判读以及安全执行约束。读完本文你将掌握从零配置到可靠调用run_gcloud_command的完整闭环并能在 Agent 场景下正确判断命令成败、规避 401/403 与交互超时等典型问题。为什么需要 MCP 而非直接执行 Shell 命令在 AI Agent 与 Google Cloud 的集成方式上gcloud SKILL.md 明确了两种主路径Direct CLI Execution在本地或自动化 Shell 环境中直接执行gcloud命令其安装、认证与配置细节见 CLI UsageModel Context Protocol (MCP)通过 Cloud CLI 远程 MCP 服务器暴露的run_gcloud_command工具以结构化工具调用方式操作 Google Cloud 资源。MCP 方式的优势在于Agent 无需在本地安装、登录并维护gcloudSDK 状态命令在一个托管的安全远程环境中执行调用方只需要携带合适的凭据即可获得与本地 CLI 等价的操作能力同时由服务端统一负责沙箱隔离、配额与审计。仓库中多个技能均采用同一套authProviderType: google_credentials的 MCP 接入范式例如 cloud-monitoring-metric-selection、datalineage-summary本指南聚焦其中的 gcloud 远程执行能力。服务器端点与工具概览Cloud CLI 远程 MCP 服务器的核心信息如下服务器端点Server Endpointhttps://cloudcli.googleapis.com/mcp传输协议TransportHTTP基于 JSON-RPC 2.0API 名称Cloud CLI Execution APIcloudcli.googleapis.com可用工具Available Toolrun_gcloud_commandrun_gcloud_command工具代表用户在托管的远程环境中安全地执行一条gcloud命令。这一“单条命令”约束与 SKILL.md 中的执行约束一脉相承——不进行命令链拼接chaining与排序禁用 Shell 操作符$(...)、|、、、以保证每条命令独立、可审计、易被用户复核。客户端配置mcp_config.json要将 MCP 客户端如 Jetski连接到远程 Cloud CLI MCP 服务器需要在mcp_config.json中配置服务条目并必须将authProviderType设为google_credentials{ mcpServers: { gcloud-remote: { serverUrl: https://cloudcli.googleapis.com/mcp, authProviderType: google_credentials } } }[!IMPORTANT] 指定authProviderType: google_credentials是强制要求。它指示 MCP 客户端附加携带https://www.googleapis.com/auth/cloud-platformOAuth 范围的 Application Default CredentialsADC。如果省略该字段客户端将发送未认证请求导致401 Unauthorized错误。这一配置范式在仓库中得到了广泛印证plugins/cloud/google-cloud-developer/gemini-extension.json中的developer-knowledgeMCP 服务器同样使用authProviderType: google_credentials声明cloud-monitoring-metric-selection/SKILL.md 在指导用户配置 Monitoring MCP 服务器时也给出了带authProviderType: google_credentials的 JSON 片段并特别强调应以merge方式合并到现有mcpServers对象避免覆盖用户已有的其他 MCP 服务器配置。为 gcloud-remote 做客户端配置时同样建议遵循这一合并策略。前置条件API 启用与 IAM 权限使用 Cloud CLI 远程 MCP 服务器前目标项目与调用身份必须同时满足两项强制性前置条件。1. 启用 Cloud CLI Execution API必须在目标项目上启用 Cloud CLI Execution APIcloudcli.googleapis.com两种方式任选其一通过 Google Cloud Console无需 CLI打开 Google Cloud Console导航至APIs Services→Library搜索Cloud CLI Execution API或直接打开该 API 的 Library 页面在项目下拉框中选择目标项目点击Enable。通过gcloudCLIgcloud services enable cloudcli.googleapis.com --project{project_id}2. IAM 角色与权限MCP 访问角色调用身份必须在目标项目上持有MCP Tool User角色roles/mcp.toolUser该角色授予mcp.tools.call权限下游资源角色调用身份还必须在被查询或修改的底层资源上持有标准 IAM 权限例如roles/compute.viewer、roles/run.developer。[!CAUTION] 只要 Cloud CLI Execution API 未启用或调用身份缺少roles/mcp.toolUser角色端点就会在工具发现tools/list和工具调用tools/call两个阶段统一返回403 Forbidden。因此排查连接问题时401 与 403 的定位方向截然不同401 指向客户端未正确附加凭据通常是authProviderType缺失403 指向服务端侧的项目配置或 IAM 授权缺失。工具参数详解调用run_gcloud_command时接受以下参数参数类型必填说明commandstring是要执行的完整gcloud命令行字符串例如gcloud compute instances list --project{resource_project} --formatjsonprojectstring是托管 Cloud CLI Execution API 的 Google Cloud 项目的资源名格式为projects/{api_project}例如projects/my-api-projectinput_files对象列表否在命令执行前预置到远程执行环境中的文件每个条目包含相对path与字符串contents关键语义API 宿主项目 vs 资源项目[!IMPORTANT]API Host Project vs. Resource Project Context顶层project参数projects/{api_project}仅用于cloudcli.googleapis.comAPI 自身的配额quota、计费billing与 API 启用状态它不会设置被执行命令的项目上下文对于项目作用域命令必须在command字符串内显式包含--project{resource_project}。目标{resource_project}不必与托管 Cloud CLI Execution API 的项目相同对于非项目作用域命令如账单或组织查询如果底层 API 需要配额项目必须在command字符串中包含--billing-project{billing_project}。这一设计与 SKILL.md 中“显式项目目标Explicit Project Target”的原则完全一致不依赖活动配置中的默认项目所有资源操作与查询命令都应显式追加--projectPROJECT_ID从而避免误操作到错误项目。在 MCP 远程执行场景下由于没有本地gcloud config环境可用显式项目参数就更加不可或缺。示例调用1. 基础命令执行{ command: gcloud compute instances list --projectmy-resource-project --formatjson, project: projects/my-cloudcli-api-project }2. 携带输入文件的命令执行{ command: gcloud run services replace service-config.yaml --regionus-central1 --projectmy-resource-project, project: projects/my-cloudcli-api-project, input_files: [ { path: service-config.yaml, contents: apiVersion: serving.knative.dev/v1\nkind: Service\nmetadata:\n name: my-service\n... } ] }第二个示例展示了input_files的典型用法当命令需要读取本地 YAML/JSON 等配置文件如gcloud run services replace、gcloud deploy apply一类的“以文件为输入”的命令时可先将文件内容以字符串形式预置到远程环境的相对路径上再在command中引用该路径。响应结构解析工具返回包含以下字段的执行响应exit_code命令执行的数字退出状态码。这是判断命令成败的首要且权威指标。stdout命令的标准输出流。stderr命令的标准错误流。output_files命令生成的文件。[!NOTE]退出码权威性Exit Code Authority当且仅当exit_code 0时命令执行成功非零exit_code表示失败。信息性stderr输出在gcloud中即使命令成功执行exit_code 0stderr也经常包含标准状态消息、进度更新以及异步跟踪 ID如--async操作 ID。Agent绝不能仅因stderr非空就断定命令失败。错误诊断如果exit_code ! 0诊断性错误消息可能出现在stderr或stdout中应同时检查两个流以理解失败原因并制定修正方案。这条“以退出码为准、宽容看待 stderr”的判读规则对 Agent 至关重要很多不熟悉 gcloud 行为的 Agent 会把进度日志误判为错误进而产生无效的重试或误报。结合 SKILL.md 中关于长耗时操作的建议——命令支持时优先追加--async并轮询操作状态——执行exit_code 0后通常还需gcloud operations describe OPERATION_ID确认异步操作最终完成。被禁止与不支持的命令Cloud CLI 远程 MCP 服务器运行在沙箱化、非交互环境中以下仅列举少量不支持的gcloud命令示例主要涉及管理本地机器配置、凭据、交互式 Shell 或元数据的命令组。该列表非穷尽且可能随时增删命令恕不另行通知gcloud auth本地认证与凭据管理gcloud config本地 CLI 配置档案与属性gcloud iam service-accounts服务账号管理gcloud init交互式安装向导gcloud survey用户反馈与调查gcloud compute ssh/gcloud app instances ssh交互式 SSH Shell理解这一限制很重要远程环境没有本地文件系统配置、没有缓存的登录态、也没有 TTY因此任何依赖本地状态或交互输入的命令天然无法工作。这正是前文要求显式传递--project、--billing-project等参数的根本原因——远程执行无法像本地 CLI 那样回退到gcloud config的默认值。安全与执行指南Cloud CLI 远程 MCP 服务器在沙箱环境中执行命令Agent 调用时必须遵守以下安全与执行约束变更类命令必须获得用户明确同意破坏性或状态变更命令如create、delete、update、patch会修改或销毁 GCP 资源不得自主调用除非用户已明确授权该操作。这与 SKILL.md 中“破坏性操作delete、update、remove必须由用户明确授权”的禁令Denylist一致后者还进一步将 IAM 策略/角色/绑定修改、gcloud billing *、gcloud organizations *、gcloud kms *等列为禁止自主执行的操作。异步操作--async对长耗时操作如创建 VM 实例、GKE 集群、数据库实例在command字符串中始终追加--async标志以避免执行超时。注意并非所有命令都支持--async需以gcloud help leaf_command的输出来确认见下文“语法验证”一节。数据缩减与格式化在command字符串中使用--formatjson、--filter、--limit限制输出体量防止上下文窗口膨胀。这也是 SKILL.md 中“数据缩减策略”的强制要求——任何list命令都必须至少携带一个数据缩减标志--limit、--filter或--format并用--formatjson(key1, key2, ...)做字段投影。非交互执行--quiet对可能弹出交互确认提示的命令包含--quiet或-q标志。Agent 运行在无 TTY、无stdin输入处理器的环境缺少--quiet时命令会因等待确认而无限挂起最终导致后台任务超时。与技能包其他准则的联动远程 MCP 执行并非游离于 gcloud 技能包之外gcloud SKILL.md 的强制前置条件同样适用于run_gcloud_command中的command字符串叶子级语法验证Mandatory所有gcloud命令、标志、标志值与位置参数的知识都可能过时并易产生幻觉。在通过 MCP 提交任何命令之前Agent 必须先执行gcloud help leaf_command例如gcloud help compute instances create验证精确叶子命令的语法父命令组的帮助如gcloud help compute不能替代叶子级验证且禁止使用 Web 搜索作为命令语法的权威来源。Schema 发现不确定--format/--filter的 JSON 键路径时先执行gcloud GROUP RESOURCE list --limit1 --formatjson探查单条资源的 JSON 结构再构造完整查询——这同样适用于远程执行场景能有效防止无约束list撑爆上下文窗口。位置Location作用域许多 Google Cloud 资源是区域级或可用区级的遗漏--region、--zone、--location会触发交互式选择提示违反“非交互执行”原则未知区域/可用区时应先执行gcloud compute regions list、gcloud compute zones list或gcloud GROUP locations list等发现命令均需携带--project。小结与速查通过 Cloud CLI 远程 MCP 服务器使用 gcloud 的核心要点可归纳为一张速查表关注点要点端点https://cloudcli.googleapis.com/mcpHTTP / JSON-RPC 2.0工具run_gcloud_command单条命令、远程沙箱执行客户端认证mcp_config.json中authProviderType: google_credentials必填否则 401API 启用gcloud services enable cloudcli.googleapis.com --project{project_id}IAM 角色roles/mcp.toolUsermcp.tools.call 下游资源角色否则 403项目语义顶层project只管配额/计费/API 启用命令级项目须在command内用--project{resource_project}指定成功判据exit_code 0stderr非空不代表失败安全约束变更类命令需用户授权长操作加--async--format/--filter/--limit缩减数据--quiet防交互挂起不支持命令gcloud auth、gcloud config、gcloud init、gcloud compute ssh等本地/交互类命令进一步阅读仓库内 MCP 使用文档 是本文的直接依据gcloud SKILL.md 提供了完整的执行模式、数据缩减、安全护栏与速查表CLI 使用文档 覆盖本地安装、认证含 ADC、服务账号密钥、身份模拟与配置管理plugins/cloud/google-cloud-developer/gemini-extension.json则展示了 Google 官方插件中对google_credentials认证方式的标准声明写法可作为配置同类 MCP 服务器的参照。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考