GCP Platform Engineer

platform-mcp

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

AI エージェント（Claude Code、Claude Desktop、または任意の MCP クライアント）を GCP プラットフォームエンジニアとして機能させる、読み取り専用のModel Context Protocolサーバーです。Google Cloud プロジェクトに接続して、インシデントの調査、インベントリの作成、コスト最適化の機会の特定を依頼できます。インフラストラクチャを変更する機能はありません。

観測のみです。 このサーバーのツールはどれも状態を変更しません。さらに、以下の閲覧専用 ID を組み合わせることで、多層防御により、エージェントは見ることはできても、決して変更できないことが確実に保証されます。

できること

領域	ツール
環境	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 を表示してください。」
• 「このプロジェクトで支出を削減できる箇所はどこですか？」

複数の環境

1 つのサーバーから複数のプロジェクトにアクセスできます。 PLATFORM_MCP_ENVIRONMENTS の下に環境を定義すると（設定を参照）、エージェントはプロンプトの表現から環境を選択します。

• 「過去 1 時間に staging でエラーはありましたか？」
• 「staging と prod の Cloud Run サービスを比較してください。」

すべてのツールは省略可能な environment 引数を受け取ります。省略するとデフォルトの環境が使用されます。別の環境を対象にするには、environment="production" を渡します。環境名、定義したエイリアス、一般的な略称（prod、stg、qa など）、およびプロジェクト ID のみの指定は、すべて解決されます。認識されない名前を指定すると、有効な選択肢を示すエラーが返されるため、タイプミスによって誤ったプロジェクトが気付かないうちに対象になることはありません。

各環境にはそれぞれ専用のサービスアカウントが割り当てられます。そのため、同じプロセスからでも staging と production には別々の ID を通じてアクセスし、すべての結果には取得元の 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 の初回セットアップ

アクセスしたいプロジェクトごとに、以下を一度実行してください。ステージング環境と本番環境では、それぞれ個別に 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. サーバーの実行に使用する ID に、読み取り専用アクセス権を付与します。

ローカル開発で自身のログイン情報（Application Default Credentials）を使う場合：

gcloud auth application-default login

この ID には、プロジェクトで以下の閲覧者ロールと、請求先アカウントで 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 が解決する ID によって実行されます。ADC 自体がなりすましサービスアカウントの場合、platform-mcp-ro ごとに roles/iam.serviceAccountTokenCreator が必要なのはユーザーではなく、その SA です。

セキュリティモデル

読み取り専用はOAuth スコープではなく IAM によって強制されます。サーバーは広範な cloud-platform スコープを要求しますが、変更を加える API を一切呼び出さないことで、読み取り専用を維持します。コードだけに頼らないでください — 上記の手順 3 のように、閲覧者権限のみを持つ ID で実行し、どのようなコードが実行されても、その認証情報では書き込みができないようにしてください。これにより、サーバーは書き込みを試みず、ID にも書き込み権限がないという、独立した 2 つの保護層が得られます。

複数の環境を使用する場合も、プロジェクトごとに分離されます。各環境はそれぞれ独自のサービスアカウントとして認証されるため、ステージング環境の ID が本番環境へのアクセスに使用されることはありません。それぞれの ID には、該当するプロジェクトのみへの閲覧者権限を付与してください。

設定

最も手軽なのは設定ファイルを使う方法です。プロジェクト 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、そうでなければ最初のエントリがデフォルトです。
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	エージェントがこの環境に使用できる追加の名前です。

文字列だけの値は {"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 という名前の環境を 1 つ公開します。

変数	用途
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__*"] } }

グロブはリテラルの mcp__<server>__ プレフィックスの後に置く必要があります。mcp__* のようにアンカーされていないパターンは警告とともに無視され、何も承認されません。

MCP Inspector — インタラクティブなテストに使用します。

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

Claude Desktop

CLI ではなく Claude Desktop を使用するチームメイト向けのインストール方法です。Claude Code と同様に動作しますが、CLI にはない失敗要因が 1 つあります。

Claude Desktop はシェルの 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 を使うのは避けてください。これらは 開発ツール一式のインストールを促すダイアログを表示するスタブです。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 をインストールする

tarball には独自の Python が同梱されているため、ほかに必要なものはありません。 brew install --cask google-cloud-sdk は避けてください。Homebrew 自体に Command Line Tools が必要です。お使いのチップに合ったビルドを選んでください。Apple Silicon では 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"

各キーについては、Configuration を参照してください。

5. 動作を確認する

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

すべての環境でチェックに合格する必要があります。Claude Desktop を開く前に、失敗した項目を修正してください。認証できないサーバーでも起動はするため、その後、すべてのツール呼び出しがエラーになります。

6. Claude Desktop の設定を編集する

Settings → Developer → Edit Config を開くか、設定ファイルを直接編集します。

OS	ファイル
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

（Settings → Connectors にはホスト型コネクターが表示されます。このサーバーのようなローカルサーバーは、そこには追加しません。）

通常、このファイルはすでに存在し、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 のパスが間違っています。

キーファイルを使わない理由

ダウンロードしたサービスアカウントキーを、サーバーの env ブロックにある GOOGLE_APPLICATION_CREDENTIALS で指定すれば、手順 2～3 を省略できます。慎重に検討してください。キーはノートパソコンに保存される有効期間の長い認証情報であり、本番環境の読み取り専用アカウントは、そのプロジェクト内のすべてのログ、メトリクス、請求データを読み取れます。 application-default login では個人に紐付いた短期間のトークンが発行され、権限を削除すれば、その人の分だけが取り消されます。

可観測性

各ツール呼び出しは、~/.local/state/platform-mcp/audit.jsonl に JSON を 1 行追記します。

{"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 を指定してください。

診断ログは stderr に出力されます（PLATFORM_MCP_LOG_LEVEL で調整できます）。stdio トランスポートでは stdout がプロトコルに使われるため、ほかの内容を出力してはいけません。Claude Code では、claude --debug=mcp でログを確認できます。

このサーバーにまったく依存しない記録を残すには、GCP で読み取り専用サービスアカウントの Data Access audit logs を有効にしてください。トークンの発行は、設定しなくても Admin Activity ログに記録されます。

開発

./.venv/bin/python -m pytest

テストスイートはインメモリの MCP クライアントを使用して実行されます。ネットワークや GCP 認証情報は不要で、環境の解決、ツールのコントラクト、アノテーション、エラーの変換、監査ログを網羅します。唯一のサブプロセスは、パッケージに含まれるセットアップスクリプトに対する bash -n で、bash がない環境ではスキップされます。

セットアップスクリプトはパッケージデータとして同梱されるため、src/platform_mcp/scripts/ にあります。platform-mcp setup はパッケージのインストール先にかかわらずスクリプトを実行するため、クイックスタートにリポジトリのチェックアウトは不要です。

備考

• すべてのツールは、トークンに配慮して結果数に上限を設け、長いペイロードを切り詰めます。
• GCP クライアントは遅延生成され、環境ごとにキャッシュされるため、会話の途中でステージング環境と本番環境を切り替える際に必要なクライアントの生成は、それぞれ 1 回だけです。
• コスト推奨機能はゾーン／リージョン単位です。list_cost_recommendations は Asset Inventory を通じてリソースがあるロケーションを自動検出し、各ロケーションに対して処理を実行します。空または利用できないロケーションや推奨機能はスキップします。skipped_calls を報告し、ロケーションを検出できない場合は明示的に失敗します。「確認できなかった」と「節約できるものがない」が同じように見えてはならないためです。
• get_cost_breakdown は、グループ化に使用できる列を許可リストで制限したパラメーター化 BigQuery クエリを使用し、選択した環境のプロジェクトで絞り込みます。請求エクスポートは請求アカウント全体を対象とするため、アカウント全体の合計が必要な場合は all_projects=true を指定してください。

ライセンス

MIT © 2026 Dimuthu Wickramanayake