Claude Media
gcloud MCPサーバーをClaude Codeに追加してGoogle Cloudを操作する
Claude CodeMCPClaude連携チュートリアル

gcloud MCPサーバーをClaude Codeに追加してGoogle Cloudを操作する

gcloud MCPサーバー(@google-cloud/gcloud-mcp)をClaude Codeに追加するコマンドと、--configのallow/deny・既定の拒否リスト・impersonationで権限を絞る方法を扱います。

読了目安 約13分

gcloud MCPサーバーは、gcloud CLIをラップしてClaude CodeなどのAIアプリケーションから自然言語でGoogle Cloudを操作できるようにするOSSです。Node.js製の単一パッケージとして配布され、「このプロジェクトのCompute Engineインスタンスを一覧して」のような指示がgcloudコマンドに変換されます。権限は接続中のgcloudアカウントにそのまま連動するため、導入後に決めることの中心は「どこまで許すか」です。

Claude Codeへの追加はclaude mcp add gcloud -- npx -y @google-cloud/gcloud-mcpの1行で済みます。Claude Desktopでは設定JSONに同じcommandとargsを書きます。Claude CodeからGoogle Cloudを操作するなら、まずClaude Codeにgcloud MCPサーバーを追加するの節に進んでください。

gcloud MCPサーバーとは — gcloud CLIをラップするnpmパッケージ

gcloud MCPサーバーはgoogleapis/gcloud-mcpリポジトリでGoogleが公開しているMCP実装で、npmパッケージ@google-cloud/gcloud-mcpとして配布されます。npmの最新版は0.5.3で、Windows対応のリファクタが入っています。

提供するツールはrun_gcloud_commandの1つだけです。入力は文字列の配列argsで、たとえば["compute", "instances", "list", "--format=json(name,status)"]のように、gcloudの後ろに続く引数を並べて渡します。任意のgcloudサブコマンドを1回の呼び出しで1つ実行するツールで、Claudeが状況に応じて必要なコマンドを組み立てます。

Google Cloudにはこれとは別に、BigQueryやCloud StorageなどをGoogle自身がホストしてHTTP経由で公開する「Google Cloud MCPサーバー」という製品群もあります。こちらはIAMのdeny/allowポリシーで統治する仕組みが用意されており、Google CloudのMCPサーバーをIAMで権限制御するで扱っています。ローカルで動く本記事のgcloud MCPサーバーとは配布形態も権限モデルも別物です。

同じリポジトリにある3つの兄弟サーバー

googleapis/gcloud-mcpリポジトリは、gcloudコマンド全般を扱うサーバーのほかに、特定のGoogle Cloud APIに特化したサーバーもホストしています。

パッケージ名扱う範囲
@google-cloud/gcloud-mcp扱う範囲gcloud CLI全般(本記事の対象)
@google-cloud/observability-mcp扱う範囲Cloud Loggingのログ・Cloud Monitoringのメトリクス・Cloud Traceのトレース・アラートポリシー・エラーグループの参照
@google-cloud/storage-mcp扱う範囲Cloud Storageのバケット・オブジェクト操作
@google-cloud/backupdr-mcp扱う範囲Backup and DR Serviceのバックアップ管理

導入方法はどれも共通で、パッケージ名を差し替えるだけです。違いが出るのはツールの形です。observability-mcpのツールは参照系です。list_log_entries・get_trace・list_alert_policies・list_group_statsのように、名前がlist_かget_で始まります。storage-mcpにはdelete_object・write_object・delete_bucketのような書き込み・削除のツールが専用で用意されています。gcloud MCPサーバーは1つのツールで何でも実行できる代わりに、書き込みを止める役目は次章以降の許可リストが担います。

Firebase・Google Analytics・GKE(Google Kubernetes Engine)・Cloud Run・MCP Toolbox for Databasesなどのサーバーは、このリポジトリの外で公開されています。READMEの「Other Google Cloud MCP Servers」に一覧があります。Cloudflareも汎用と製品別のMCPサーバー群を公式提供しており、Cloudflare MCPサーバー一覧にまとめています。

Claude Codeにgcloud MCPサーバーを追加する

前提はNode.js 20以上と、ローカルにインストール済みのgcloud CLIです。

手順

導入の3ステップ

  1. 1

    gcloudで認証する

    gcloud auth login(またはgcloud init)で認証を済ませておきます。MCPサーバーが使うのは、このとき有効になっているアカウントです。gcloud auth application-default loginはクライアントライブラリ向けのADCを作るもので、gcloudコマンドの認証には使われません。

  2. 2

    claude mcp addで登録する

    --より後ろがサーバーを起動するコマンドとして、そのまま渡されます。

    claude mcp add gcloud -- npx -y @google-cloud/gcloud-mcp
  3. 3

    接続を確かめる

    claude mcp get gcloudかclaude mcp listで状態を見ます。

Claude Code v2.1.287のclaude mcp add --helpでは、-s, --scope <scope>の既定値はlocalと表示されます。選べるのはlocal・user・projectの3つです。チーム全員に配りたい場合は--scope projectを付けて.mcp.jsonにコミットします。ただしプロジェクトスコープのサーバーは、各自がclaudeを起動して承認するまで⏸ Pending approvalのままです。claude mcp addのスコープ・認証・トラブルシュートの詳しい仕様はClaude Code MCP設定ガイドにまとめています。

Claude Desktopではclaude_desktop_config.jsonのmcpServersに同じ形のJSONを書きます。

{
  "mcpServers": {
    "gcloud": {
      "command": "npx",
      "args": ["-y", "@google-cloud/gcloud-mcp"]
    }
  }
}

commandとargsの値は他のクライアントでも共通です。ただしトップのキーはクライアントごとに違い、READMEのVisual Studio Code向けの例ではmcpServersではなくserversになっています。Cursorは.cursor/mcp.json(プロジェクト単位)か~/.cursor/mcp.json(全プロジェクト)です。Gemini CLI向けにはnpx @google-cloud/gcloud-mcp init --agent=gemini-cliという専用コマンドがあり、ホームディレクトリで実行するとGemini CLI拡張としてユーザー単位に登録されます。

run_gcloud_commandは1コマンドずつ実行する

run_gcloud_commandのツール定義には、モデル向けの指示が埋め込まれています。実務に直結する制約は次の3つです。

  • パイプ・リダイレクト・サブシェルの禁止: |や>、$(...)のようなシェル演算子は使いません
  • コマンドチェーンの禁止: 1回の呼び出しで複数コマンドを連結する実行は失敗します
  • SSH系コマンドとgcloud interactive: 失敗するとツール説明に書かれています

READMEの謳い文句には「複数のクラウド操作を1つの繰り返し可能なコマンドにチェーンできる」とありますが、シェルレベルの連結ではありません。Claudeがrun_gcloud_commandを会話の中で複数回呼び、1ステップずつ結果を見ながら進めます。「停止中インスタンスを一覧して、ラベルを確認してから削除して」という指示は、一覧取得・ラベル確認・削除の3回のツール呼び出しになります。

出力を絞る指示も入っています。--format=json(part.key)のような射影で必要な列だけを取る、フィルタ条件が分からないときは--limit=1 --format=jsonで1件だけ取ってキー構造を確かめる、といった内容です。--filterではコロンの右側をクォートしないという作法まで指定されており、出力サイズを抑えて、コンテキストを圧迫しにくくします。

コマンドが終了コード0以外を返したときや標準エラー出力があったときは、標準出力の後ろにSTDERR:として続けて返します。Claudeは成功した出力と警告を同じ結果の中で読むことになります。

デフォルトで拒否されるコマンド

組み込みの拒否リストは、公式ドキュメントで「常に有効で、利用者は設定で変えられない」とされています。READMEは目的を「任意の入力を実行したり対話セッションを始めたりするコマンドを、AIエージェントには意味がないので止めるため」と説明しています。

拒否されるコマンド種類
compute ssh / cloud-shell ssh / workstations ssh / app instances ssh種類SSHセッション
compute tpus tpu-vm ssh / compute tpus queued-resources ssh種類TPU VMへのSSH
compute start-iap-tunnel / compute connect-to-serial-port種類トンネル・シリアルポート接続
interactive種類対話シェル
meta種類gcloudのmetaグループ

照合は前方一致です。appはapp deployに当たりますがapphubには当たりません。拒否リストにGA版のコマンドがあると、同じコマンドのalpha・betaも拒否されます。

拒否されたとき、ツールは別のリリーストラック(GA・beta・alpha・preview)で許可されている同じコマンドを探し、見つかればそれを使うよう促すエラーを返します。見つからなければ、拒否リストの内容を見る方法を添えたエラーになります。その方法が、ツールに["gcloud-mcp", "debug", "config"]を渡す呼び出しです。

許可リストと拒否リストを--configで足す

既定の拒否リストに加えて、利用者が自分で許可リストか拒否リストを足せます。JSONの設定ファイルを作り、-cか--configで渡します。

くらべる

設定ファイルは allow か deny のどちらか一方

書いたものだけ通す

allow(許可リスト)

{
  "allow": ["compute instances list", "compute instances describe"]
}

指定した前方一致のコマンドだけが通ります。書いていないコマンドは、拒否リストに無くても実行されません。

書いたものだけ止める

deny(拒否リスト)

{
  "deny": ["compute instances delete", "alpha", "beta"]
}

指定したコマンドだけが止まり、ほかは通ります。alphaのようにリリーストラック名だけを書くと、そのトラックを丸ごと拒否します。

Claude Codeへの渡し方は次のとおりです。--より後ろはclaudeの引数として解釈されず、そのままサーバーに届きます。

claude mcp add gcloud -- npx -y @google-cloud/gcloud-mcp --config /abs/path/gcloud-mcp.json

守る点は4つあります。

  • allowとdenyを両方書くとエラーで起動しません
  • 設定ファイルのパスは絶対パスでなければなりません。相対パスだとエラーで終了します
  • 許可リストのエントリは、そのリリーストラックだけを許可します。beta storageはbetaのstorageコマンドを通しますが、GA版のstorageは通しません
  • 既定の拒否リストは、許可リストを書いても必ず残ります

allowにcompute instancesとだけ書くと、同じグループのdeleteも通ります。参照だけに絞るなら、compute instances listやdescribeのようにサブコマンドまで書きます。絶対パスが必須なので、--scope projectで.mcp.jsonに書いて共有するときは、全員のマシンで同じパスに設定ファイルを置く必要があります。

権限はgcloudアカウントにひもづく

許可リストと拒否リストが決めるのは「どのコマンドか」だけで、「誰の権限で実行するか」は別に決まります。gcloud MCPサーバーの実行権限は、接続時にアクティブなgcloudアカウントの権限にそのまま連動します。個人の開発環境でOwner権限のアカウントを使っていれば、AIエージェントも同じOwner権限で動きます。使われているアカウントはgcloud config get-value accountで確認できます。

どこで止めるか

権限を絞る3つの層

  • コマンドの層(--config)

    gcloudのコマンドグループ単位で通す・止めるを決めます。フラグや対象リソースまでは区別できません。

  • IDの層(impersonation)

    サービスアカウントになりすまして実行します。権限の範囲はIAMのロールで決まり、MCPサーバーの設定とは独立です。

  • 依頼の層(プロンプト)

    対象プロジェクトIDを依頼文に書きます。Claudeに伝わるだけで、強制力はありません。

最小権限で運用するなら、サービスアカウントのimpersonation(なりすまし)を使います。まず自分のプリンシパル(IAMでの権限の付与対象)に、対象サービスアカウントへのroles/iam.serviceAccountTokenCreatorロールを付与してもらいます。そのうえで次のコマンドを実行します。

gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_EMAIL

以降のすべてのgcloudコマンドが、MCPサーバー経由かターミナルからかを問わず、指定したサービスアカウントの権限で実行されます。単発で試したいときは、コマンドごとに--impersonate-service-accountフラグを付ける方法もあります。サービスアカウント側には、Compute Engineの参照専用ロールのような、業務に必要な最小限のロールだけを割り当てます。

これらはgcloud CLI全般に共通するIAMの話です。Google自身がホストする「Google Cloud MCPサーバー」がMCP呼び出しに要求するmcp.tools.callパーミッションとは別の仕組みです。「本番環境には読み取り専用のIDだけを渡す」という設計方針は他のMCPサーバーにも共通で、Kubernetes向けの例はKubernetes MCPサーバーの権限設計で扱っています。

使う場面ごとの制限の選び方

  • 個人の環境でリソースを確認したい: 既定のまま使えます。ただしOwnerのアカウントなら削除も通るので、denyにcompute instances deleteのような破壊系を足しておく選択肢があります
  • 本番プロジェクトにも触れさせたい: --configのallowに参照系だけを書き、さらにimpersonationで参照専用ロールのサービスアカウントを使えば、コマンドとIDの両方で止まります。どちらか片方では、もう片方の抜け穴が残ります
  • ログだけ調べたい: observability-mcpを入れる選択肢があります

よくあるつまずき

  • 「一気にやって」と頼んでも1ステップずつ進む: run_gcloud_commandはコマンドチェーンを受け付けません。Claudeが複数回ツールを呼ぶのを待つか、手順を分けて依頼します
  • SSHで入りたい操作が動かない: compute ssh系は既定の拒否リストに入っており、設定で外せません。対話操作はターミナルから直接gcloudを実行します
  • 意図しないプロジェクトで実行される: gcloud config get-value projectでアクティブプロジェクトを確認してから依頼します。プロジェクトをまたぐ操作では、依頼文に対象プロジェクトIDを書いておきます
  • APIが有効化されていないというエラーが出る: ツールの指示には「必要なAPIは有効化済みと仮定し、勝手に有効化しない」とあります。事前にgcloud services enableで有効化しておきます
  • 設定ファイルを渡したのに起動しない: 相対パス・allowとdenyの併記・JSONの構文エラーのいずれかが原因になります。どれもサーバー起動時にエラーで終了します
  • 許可したはずのコマンドが拒否される: 許可リストはリリーストラック単位です。gcloud beta経由で呼ばれていれば、GA版だけを書いた許可リストには当たりません。このとき別トラックで許可されている同じコマンドがあれば、そちらでの再実行を促すエラーが返ります

まとめ

本番プロジェクトに触れさせるかどうかで、必要な設定が分かれます。触れさせないなら、denyに破壊系コマンドを足すだけで足ります。触れさせるなら、allowで参照系に絞ることと、参照専用ロールのサービスアカウントで実行することの両方が要ります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →