GCP Platform Engineer

platform-mcp

mcp-name: io.github.deBilla/platform-mcp

一个只读的 Model Context Protocol 服务，可将 AI Agent（Claude Code、Claude Desktop 或任何 MCP 客户端）变成 GCP 平台工程师。将它连接到你的 Google Cloud 项目，让它调查事件、清点资源并发现成本优化机会——且完全无法更改你的基础设施。

仅供观察。 此服务中的任何工具都不会修改状态。结合仅具查看权限的身份（见下文），可提供严格的纵深防御保障，确保 Agent 只能查看，绝不能操作。

功能

领域	工具
环境	list_environments
日志与错误	query_logs、get_recent_errors、list_error_groups
指标与告警	query_metric、list_alert_policies、list_uptime_checks
成本与建议	get_cost_breakdown、get_billing_info、list_cost_recommendations、list_recommendations
资源清单	search_assets、list_compute_instances、list_cloud_run_services、list_gke_clusters、list_sql_instances

连接后可以尝试以下提示词：

• “过去 24 小时内最重要的错误组有哪些？其中最新的是哪个？”
• “哪些 GKE 节点池配置过度？请显示平均 CPU 使用率和机器类型。”
• “我可以在哪里降低这个项目的支出？”

多个环境

一个服务可以访问多个项目。在 PLATFORM_MCP_ENVIRONMENTS 下定义环境（参见配置），Agent 会根据提示词措辞选择环境：

• “过去一小时内 staging 有错误吗？”
• “比较 staging 和 prod 中的 Cloud Run 服务。”

每个工具都接受可选的 environment 参数。省略该参数时会使用默认 环境；传入 environment="production" 则会指定其他环境。环境名称、 你定义的别名、常见缩写（prod、stg、qa 等）以及完整的项目 ID 均可解析。无法识别的名称会报错并列出有效选项——拼写错误绝不会悄悄地将目标切换到错误的项目。

每个环境都有自己的服务账号，因此 staging 和 production 会通过同一进程中的不同身份访问，并且每个结果 都会显示其来源的 environment 和 project。

要求

• Python 3.11+
• 一个 Google Cloud 项目和凭据（你自己的登录凭据或服务账号）
• 用于一次性设置的 gcloud CLI

安装

uvx platform-mcp          # no install step; uv fetches it on demand
pipx install platform-mcp # or keep it on PATH

从检出目录进行开发：

git clone https://github.com/deBilla/platform-mcp.git
cd platform-mcp
python3 -m venv .venv
./.venv/bin/pip install -e ".[dev]"

检查设置

platform-mcp doctor

此命令会检查每个已配置的环境，确认 Application Default Credentials 是否存在、只读服务账号是否可以模拟、实际 API 读取是否成功，以及结算导出是否可读取——并打印修复失败项所需的准确命令。报告问题前请先运行此命令。

一次性 GCP 设置

对你想要访问的每个项目各执行一次 — staging 和 production 都需要分别启用 API，并各自拥有一个只读服务账号。

1. 启用工具所依赖的 API：

gcloud services enable \
  logging.googleapis.com monitoring.googleapis.com clouderrorreporting.googleapis.com \
  recommender.googleapis.com cloudasset.googleapis.com cloudbilling.googleapis.com \
  bigquery.googleapis.com \
  --project YOUR_PROJECT_ID

2. 向服务运行时使用的身份授予只读访问权限。

使用你自己的登录凭据进行本地开发（Application Default Credentials）时：

gcloud auth application-default login

该身份需要在项目上拥有以下查看者角色，并在结算账号上拥有 roles/billing.viewer：

roles/viewer                # broad read (compute, run, gke, sql via Asset Inventory)
roles/logging.viewer
roles/monitoring.viewer
roles/errorreporting.viewer
roles/recommender.viewer
roles/cloudasset.viewer
roles/bigquery.dataViewer    # only for get_cost_breakdown
roles/bigquery.jobUser       # only for get_cost_breakdown

3.（推荐）使用专用只读服务账号，而不是使用你的登录凭据。platform-mcp setup 会完成以下所有步骤，可安全地重复运行，并在最后打印配置片段。它随软件包一同提供，无需克隆：

uvx platform-mcp setup \
  --project YOUR_PROJECT_ID \
  --user [email protected] \
  --billing-dataset YOUR_BILLING_PROJECT:billing   # optional

或者手动操作：

PROJECT=YOUR_PROJECT_ID
gcloud iam service-accounts create platform-mcp-ro \
  --display-name "platform-mcp read-only" --project $PROJECT

SA=platform-mcp-ro@$PROJECT.iam.gserviceaccount.com
for ROLE in roles/viewer roles/logging.viewer roles/monitoring.viewer \
  roles/errorreporting.viewer roles/recommender.viewer roles/cloudasset.viewer \
  roles/bigquery.jobUser; do
  gcloud projects add-iam-policy-binding $PROJECT \
    --member="serviceAccount:$SA" --role="$ROLE" --condition=None
done

# Let your own login impersonate it (no key file to manage):
gcloud iam service-accounts add-iam-policy-binding $SA \
  --member="user:[email protected]" \
  --role="roles/iam.serviceAccountTokenCreator" --project $PROJECT

最容易被忘记的授权。 上面的 roles/bigquery.jobUser 仅允许账号启动查询，不会授予任何数据访问权限。结算导出几乎总是位于另一个项目中，因此该账号还需要拥有对该数据集的读取权限。缺少此权限时，get_cost_breakdown 会返回 403，而其他所有工具都能正常工作，看起来像是工具本身有问题，而不是缺少授权：

bq add-iam-policy-binding \
  --member="serviceAccount:$SA" --role=roles/bigquery.dataViewer \
  YOUR_BILLING_PROJECT:billing

如果你没有结算项目的管理员权限，请把这一行发给拥有该权限的人。platform-mcp doctor 会检查此项，并指出缺少哪一侧的权限。

然后在 PLATFORM_MCP_ENVIRONMENTS 中，将它设为该环境的 impersonate 值（推荐 — 无需密钥文件），或者通过 GOOGLE_APPLICATION_CREDENTIALS 指向下载的密钥。

模拟身份所使用的是 ADC 解析出的身份。如果你的 ADC 本身模拟了某个服务账号，那么需要在每个 platform-mcp-ro 上拥有 roles/iam.serviceAccountTokenCreator 的是该 SA，而不是你的用户账号。

安全模型

只读权限由 IAM 而非 OAuth 范围强制执行。服务会请求范围较广的 cloud-platform 范围，并且仅仅因为它从不调用会修改数据的 API，才保持只读。不要只依赖代码 — 使用仅拥有查看者权限的身份运行它（见上面的步骤 3），确保凭据本身无法写入，无论执行什么代码。这为你提供了两层独立保护：服务不会尝试写入，而身份即使尝试也无法写入。

使用多个环境时，权限仍按项目隔离：每个环境都以自己的服务账号进行身份验证，因此 staging 身份绝不会用于访问 production。仅向每个服务账号授予其自身项目的查看者权限。

配置

最方便的方式是使用配置文件，这样就不必在每个客户端配置中重复填写项目 ID 和服务账号邮箱：

mkdir -p ~/.config/platform-mcp
cp config.toml.example ~/.config/platform-mcp/config.toml
$EDITOR ~/.config/platform-mcp/config.toml

配置好之后，注册服务无需任何环境变量。将 PLATFORM_MCP_CONFIG 指向其他位置，即可使用不同的文件，例如提交到基础设施仓库的副本。

环境变量仍然有效，并且始终优先于文件，因此现有配置可以照常运行，临时覆盖也无需编辑文件：

变量	用途
PLATFORM_MCP_ENVIRONMENTS	环境名称 → 设置的 JSON 映射。推荐使用此方式配置服务。
PLATFORM_MCP_DEFAULT_ENVIRONMENT	工具调用未提供 environment 时使用的环境。若已配置 staging，则默认为 staging；否则使用第一项。
GOOGLE_APPLICATION_CREDENTIALS	只读 SA 密钥文件的路径（作为模拟身份的替代方式）。

PLATFORM_MCP_ENVIRONMENTS 保存一个 JSON 对象；每个条目可接受以下内容：

键	用途
project	必填。 GCP 项目 ID。
impersonate	此环境要模拟身份的只读 SA（无需密钥文件）。
billing_export_table	完全限定的 BigQuery 账单导出表，仅 get_cost_breakdown 必填（例如 YOUR_PROJECT_ID.billing.gcp_billing_export_v1_XXXXXX）。
aliases	Agent 可用于此环境的其他名称。

字符串值可简写为 {"project": "..."}。在 .mcp.json 中以 JSON 形式写入时，必须转义引号；未转义时如下所示：

{
  "staging": {
    "project": "my-app-staging",
    "impersonate": "[email protected]"
  },
  "production": {
    "project": "my-app",
    "impersonate": "[email protected]",
    "billing_export_table": "my-app.billing.gcp_billing_export_v1_XXXXXX"
  }
}

单环境模式。 如果未设置 PLATFORM_MCP_ENVIRONMENTS，服务的行为与之前相同，只提供一个名为 default 的环境：

变量	用途
GCP_PROJECT	目标项目。若未设置，则使用 ADC 默认项目。
IMPERSONATE_SERVICE_ACCOUNT	要模拟身份的只读 SA。对于未设置 impersonate 的注册表条目，也会作为回退值。
BILLING_EXPORT_TABLE	账单导出表。对于未设置 billing_export_table 的注册表条目，也会作为回退值。

与客户端注册

Claude Code — 配置文件就绪后，只需以下配置：

claude mcp add platform-mcp --scope user -- uvx platform-mcp

Claude Desktop — 需要提供 uvx 的绝对路径；完整操作步骤请参阅 Claude Desktop。

如果没有配置文件，请将 .mcp.json.example 中的环境变量添加到任一形式的配置中。

跳过审批提示

这里的所有工具均为只读，因此逐个批准调用没有意义。在 Claude Code 设置中一次性允许整个服务：

{ "permissions": { "allow": ["mcp__platform-mcp__*"] } }

glob 必须紧跟在字面前缀 mcp__<server>__ 之后；像 mcp__* 这样未锚定的模式会被忽略，并显示警告，且不会批准任何内容。

MCP Inspector — 用于交互式测试：

uvx --with 'mcp[cli]' mcp dev src/platform_mcp/server.py

Claude Desktop

为使用 Claude Desktop 而非 CLI 的队友安装。它的工作方式与 Claude Code 相同，但有一种 CLI 不会遇到的故障情况。

Claude Desktop 不会继承 shell 的 PATH。 它从 Finder 启动，因此无法访问 uvx 以及通过 Homebrew 或 uv 安装的任何内容。配置中写 "command": "uvx" 会导致 ENOENT——服务无法启动，错误信息会指出命令，而不是失败原因。命令路径必须是绝对路径。

凭证不会因此失效。应用默认凭证是 Google 库直接读取的文件，因此只需在终端中运行一次 gcloud 来创建该文件——运行时不需要它。无论由什么程序启动服务，配置文件都会以相同方式从主目录中找到。

开始之前：管理员授权

每个人都会模拟只读服务账号，因此管理员需要为每个人、每个环境运行一次以下操作（platform-mcp setup 脚本会为运行脚本的人执行此操作，但不会为其他人执行）：

gcloud iam service-accounts add-iam-policy-binding \
  platform-mcp-ro@YOUR_PROJECT_ID.iam.gserviceaccount.com \
  --member="user:[email protected]" \
  --role="roles/iam.serviceAccountTokenCreator" --project YOUR_PROJECT_ID

如果未执行此操作，所有内容都会正常安装，但 doctor 会在模拟身份步骤失败。

1. 安装 uv（macOS）

分析师的笔记本电脑通常既没有 Homebrew，也没有 Xcode Command Line Tools，而这里不需要它们。整个过程中请避免使用 git、make 和系统自带的 /usr/bin/python3——它们都是会弹出对话框、提示安装 GB 级开发工具的存根。 uv 是独立的二进制文件：

curl -LsSf https://astral.sh/uv/install.sh | sh
which uvx      # note this absolute path — Claude Desktop needs it

通常位于 /Users/<you>/.local/bin/uvx。

2. 安装 Google Cloud CLI

这个压缩包自带 Python，因此不需要其他东西。请避免使用 brew install --cask google-cloud-sdk：Homebrew 本身就需要 Command Line Tools。选择适合你的芯片的版本——Apple 芯片上 uname -m 会输出 arm64，Intel 芯片上则会输出 x86_64：

# Apple Silicon
curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-arm.tar.gz
tar -xzf google-cloud-cli-darwin-arm.tar.gz

# Intel — same, with the other file
# curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-x86_64.tar.gz
# tar -xzf google-cloud-cli-darwin-x86_64.tar.gz

./google-cloud-sdk/install.sh --quiet

3. 进行身份验证

./google-cloud-sdk/bin/gcloud auth application-default login

请以你本人的身份登录。如果你的 ADC 本身就是一个模拟身份的服务账号，那么 进行模拟的身份就是该账号，而不是你本人；它不会拥有上述授权。

4. 编写配置文件

mkdir -p ~/.config/platform-mcp
touch ~/.config/platform-mcp/config.toml
open -e ~/.config/platform-mcp/config.toml   # or any editor

default_environment = "staging"

[environments.staging]
project = "my-app-staging"
impersonate = "[email protected]"

[environments.production]
project = "my-app"
impersonate = "[email protected]"
billing_export_table = "my-app.billing.gcp_billing_export_v1_XXXXXX"

所有键的说明，请参阅配置。

5. 检查是否成功

~/.local/bin/uvx platform-mcp doctor

每个环境都应该通过检查。请先修复所有失败项，再打开 Claude Desktop——无法进行身份验证的服务仍然会启动，但之后每次工具调用都会报错。

6. 编辑 Claude Desktop 配置

设置 → 开发者 → 编辑配置可以打开配置文件，也可以直接编辑：

操作系统	文件
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

（设置 → 连接器列出托管连接器；像这个这样的本地服务不会添加到那里。）

该文件通常已存在，并保存着你的 Desktop 偏好设置。 将 mcpServers 作为另一个顶层键添加进去——不要替换该文件，否则会丢失这些设置：

{
  "preferences": { "...": "your existing settings, left alone" },
  "mcpServers": {
    "platform-mcp": {
      "command": "/Users/YOU/.local/bin/uvx",
      "args": ["platform-mcp@latest"]
    }
  }
}

将 /Users/YOU/.local/bin/uvx 替换为 which uvx 输出的路径。在 Windows 上，路径类似 C:\\Users\\YOU\\.local\\bin\\uvx.exe——在 JSON 中反斜杠要加倍。 @latest 会让每次启动都获取最新版本。

重启前请检查文件仍能解析——多出的逗号会悄无声息地禁用所有服务。这只使用 macOS 自带的工具：

osascript -l JavaScript -e 'function run(a){ObjC.import("Foundation");JSON.parse($.NSString.stringWithContentsOfFileEncodingError(a[0],4,null).js);return "valid"}' \
  ~/Library/Application\ Support/Claude/claude_desktop_config.json

7. 重启 Claude Desktop

完全退出（Cmd-Q，而不仅仅是关闭窗口），然后重新打开。接着询问 “列出已配置的环境”——它应该会通过 list_environments 作答。

如果它没有出现，日志位于 ~/Library/Logs/Claude/ （mcp-server-platform-mcp.log）。其中的 ENOENT 表示 command 路径错误。

为什么不使用密钥文件？

你可以将 GOOGLE_APPLICATION_CREDENTIALS（位于服务的 env 块中）指向下载的服务账号密钥文件，从而跳过第 2–3 步。请三思：密钥是 存放在笔记本电脑上的长期有效凭据，而生产环境的只读账号可以读取该项目中的每条 日志、每项指标和每条账单记录。application-default login 会签发与个人身份关联的 短期令牌，撤销授权只会影响该个人。

可观测性

每次工具调用都会在 ~/.local/state/platform-mcp/audit.jsonl 中追加一行 JSON：

{"ts":"2026-08-30T18:20:11+0800","tool":"query_logs","environment":"production",
 "project":"my-app","duration_ms":412,"count":50,"bytes":18422,"error":null}

自由文本参数只会按名称记录——Cloud Logging 过滤条件可能会包含从所搜索日志中提取的 用户 ID，而审计文件不应成为这些信息的第二份副本。将 PLATFORM_MCP_AUDIT_LOG 设为其他路径，或设为 off。

诊断日志会写入标准错误（通过 PLATFORM_MCP_LOG_LEVEL 调整）；在 stdio 传输模式下，标准输出承载协议，因此不得向其中写入其他内容。在 Claude Code 中，可通过 claude --debug=mcp 查看日志。

如需一份完全不依赖此服务的记录，请在 GCP 中为只读服务账号启用数据访问审计日志。 令牌铸造记录无需任何配置，就已出现在管理活动日志中。

开发

./.venv/bin/python -m pytest

测试套件使用内存中的 MCP 客户端运行——无需网络，也无需 GCP 凭据——并覆盖环境解析、工具契约、注解、错误转换和审计日志。唯一的子进程是在打包的设置脚本上运行 bash -n；没有 bash 的环境会跳过此项。

设置脚本位于 src/platform_mcp/scripts/，因为它会作为包数据一同发布；无论软件包安装在哪里，platform-mcp setup 都会从那里运行，因此快速入门无需检出代码库。

备注

• 所有工具都会限制结果数量，并截断较长的负载，以控制令牌用量。
• GCP 客户端会延迟构建，并按环境缓存，因此在对话中途切换测试环境和生产环境时，各自只需构建一个客户端。
• 费用建议器按可用区或区域提供建议；list_cost_recommendations 会自动发现你拥有资源的位置（通过 Asset Inventory），并在这些位置上并行查询，同时跳过结果为空或不可用的位置和建议器。它会报告 skipped_calls；如果无法发现任何位置，则会明确报错，因为“无法查询”和“没有可节省的费用”不应混为一谈。
• get_cost_breakdown 使用参数化 BigQuery 查询，并将分组列限制在白名单范围内，同时筛选所选环境的项目。结算导出涵盖整个结算账号，因此如果要获取账号范围的汇总，请传入 all_projects=true。

许可证

MIT © 2026 Dimuthu Wickramanayake