Claude Media
ArgoCD MCPサーバーでGitOpsデプロイをClaudeに任せる
Claude CodeMCPClaude連携チュートリアル

ArgoCD MCPサーバーでGitOpsデプロイをClaudeに任せる

argoproj-labs公式のArgoCD MCPサーバーで、アプリケーションの同期やリソースのトラブルシュートを自然言語から行う手順をまとめます。

読了目安 約13分

ArgoCD MCPサーバー(argoproj-labs/mcp-for-argocd)は、Argo CD公式org配下で開発されているMCPサーバーです。アプリケーションの同期・リソースツリーの確認・ワークロードのログ取得までを、Claude Codeから自然言語で操作できます。

ArgoCD MCPサーバーとは

GitOpsの運用では、Gitにpushしたマニフェストが実際のクラスタにいつ・どう反映されたかを追いかける作業が日常的に発生します。ArgoCD MCPサーバーはこの確認作業をAIエージェント経由に置き換えるためのサーバーで、stdioとHTTP streamの両方のトランスポートに対応しています。個人のローカル利用ならstdio、チームで共有するならHTTPモードという住み分けです。

前提として必要なのはNode.js(v18以上)とAPIアクセス可能なArgoCDインスタンスです。管理者アカウントで発行したトークンをそのまま使うこともできますが、ArgoCDにはAppProjectごとにRoleを定義し、そのRole用のJWTトークンだけを発行する仕組み(argocd proj role create-token)があります。特定アプリケーションへの同期操作だけを許すRoleを作ってそのトークンを渡せば、MCPサーバー側の設定と合わせて二重に権限を絞れます。同様にHCP TerraformのワークスペースをMCPから操作する場合も、APIトークンの権限を必要最小限に絞ることが推奨されています。

Claude Codeへの追加手順

必要なのはArgoCDのベースURLとAPIトークンの2つです。トークンはArgoCDの管理画面かCLIから発行します。

claude mcp add-json argocd-mcp \
  '{"command":"npx","args":["argocd-mcp@latest","stdio"],"env":{"ARGOCD_BASE_URL":"<argocd_url>","ARGOCD_API_TOKEN":"<argocd_token>"}}' \
  -s user

自己署名証明書を使うArgoCDインスタンスに繋ぐ場合は、NODE_TLS_REJECT_UNAUTHORIZEDを0にする環境変数を追加します。ただしこれはTLS検証そのものを無効化する設定なので、開発環境限定の一時的な回避策として扱います。

APIトークンはツール呼び出しの引数としては一切受け付けません。HTTPヘッダーか環境変数からしか読み込まない設計になっており、これはトークンがプロンプトやモデルのコンテキストに混入しないようにするためです。MCPサーバーへの一般的な追加コマンドの構文やスコープの使い分けはClaude Code MCP設定ガイドにまとめています。

Cursor・VS Codeへの追加手順

設定の中身はClaude Codeと同じで、クライアントごとに設定ファイルの置き場所が変わるだけです。Cursorなら.cursor/mcp.jsonに、次のブロックを追加します。

{
  "mcpServers": {
    "argocd-mcp": {
      "command": "npx",
      "args": ["argocd-mcp@latest", "stdio"],
      "env": {
        "ARGOCD_BASE_URL": "<argocd_url>",
        "ARGOCD_API_TOKEN": "<argocd_token>"
      }
    }
  }
}

VS CodeはMCP対応のCopilot Chatから使う想定で、.vscode/mcp.jsonにtype: "stdio"を明示したブロックを置きます。ワンクリックインストール用のリンクも公式リポジトリで配布されているため、手でJSONを書きたくない場合はそちらを使えます。どのクライアントでも、APIトークンをファイルに直書きせず環境変数経由で渡す運用にしておくと、設定ファイルをリポジトリに誤ってコミットしてしまうリスクを避けられます。

提供ツール一覧

ツールはクラスタ・プロジェクト・アプリケーション・リソースの4系統に分かれています。

系統主なツールできること
クラスタ主なツールlist_clustersできることArgoCDに登録済みのクラスタを一覧する
プロジェクト主なツールget_appprojectできることAppProjectの詳細を取得する
アプリケーション主なツールlist_applications / get_application / create_application / update_application / delete_application / sync_applicationできることアプリケーションの作成・更新・同期・削除
リソース主なツールget_application_resource_tree / get_application_managed_resources / get_application_workload_logs / get_resource_events / run_resource_actionできること個々のリソースの状態確認とアクション実行

sync_applicationが同期のトリガーで、get_application_workload_logsがPodやDeploymentのログ取得にあたります。障害調査ではget_resource_eventsと組み合わせて、いつ何が起きたかを時系列で追えます。

get_application_managed_resourcesは、ArgoCDが実際に管理しているリソースの一覧と、Git側の定義とクラスタ上の実体との差分を返します。手動でクラスタに変更を加えてArgoCDの管理外にドリフトした箇所を見つけるのに使えます。get_resource_actionsはリソースごとに実行可能なアクション(再起動・ロールバックなど)を調べるツールで、run_resource_actionと対にして使うと、まず何ができるかを確認してから実行に移す流れになります。

ネットワーク公開時の安全設計

httpやsseトランスポートはネットワークリスナーを開き、create_applicationやdelete_applicationを含むすべてのツールに到達可能にします。既定のバインドアドレスは127.0.0.1(ループバックのみ)で、外部に公開しない限りは安全側です。

バインドを0.0.0.0のように広げる場合、MCP_AUTH_TOKEN環境変数を設定しないと起動そのものが失敗します。フロントに認証済みのプロキシがある構成なら--allow-unauthenticatedで意図的にこの制約を外せますが、それ以外では起動を拒否するフェイルクローズの設計です。

export MCP_AUTH_TOKEN=<inbound_token>
node dist/index.js http --bind-address 0.0.0.0 \
  --allowed-host-header mcp.internal.example.com

書き込み系のツールを封じたいだけなら、MCP_READ_ONLYをtrueにする方法もあります。create_application・update_application・delete_application・sync_application・run_resource_actionが無効になり、閲覧系ツールだけが残ります。ネットワーク公開の認証(誰が呼べるか)と読み取り専用モード(何ができるか)は別レイヤーの制御なので、チーム共有のHTTPサーバーでは両方を組み合わせるのが安全です。

複数インスタンスをトークンレジストリで扱う

ステージングと本番でArgoCDインスタンスが分かれているチームでは、ARGOCD_TOKEN_REGISTRY_PATHでトークンレジストリのJSONファイルを指定できます。

[
  { "baseUrl": "https://argo-staging.example.com", "token": "<token-staging>" },
  { "baseUrl": "https://argo-prod.example.com", "token": "<token-prod>" }
]

環境変数で渡す既定トークンは、その既定のベースURL以外には絶対に送られません。ツール呼び出しのargocdBaseUrl引数で任意のホストを指定できてしまう以上、既定トークンを無条件にどのホストにも送る設計だと、プロンプトインジェクションで別ホストへトークンが漏れる経路になります。レジストリに登録されていないホストへのアクセスは、トークンが解決できずにエラーで止まります。レジストリファイルはchmod 400などで権限を絞り、Kubernetes Secretのマウントのような形で配置することが推奨されています。

実際にGitOpsデプロイを任せてみる

接続後は「production環境のAppを同期して」のような指示でsync_applicationが呼ばれます。同期が失敗した場合は「なぜ同期に失敗したか調べて」と続けると、get_application_resource_treeとget_resource_eventsを組み合わせてClaude Codeが原因を追跡します。単に状態を聞くだけでなく、失敗したリソースに対してrun_resource_actionで再起動などのアクションを実行することもできます。

同期先のクラスタ内部まで踏み込んで調べたいときは、Kubernetes MCPサーバーを併用します。ArgoCD側でアプリケーションが「Degraded」と分かったあと、実際のPodのログやイベントの中身はKubernetes MCPサーバー経由で追う、という役割分担です。ArgoCDはマニフェストと実クラスタの差分を管理するツールで、Pod内部の挙動そのものまでは見に行かないため、この2つを組み合わせて初めてGitPushからPodの中身まで一本の会話でたどれます。

stdioとHTTP、単一インスタンスと複数インスタンスの使い分け

構成向くケース理由
stdio + 単一トークン向くケース個人のローカル開発理由設定が最小で、プロセス起動と同時に使える
HTTP + MCP_AUTH_TOKEN向くケースチームで1つのArgoCDインスタンスを共有理由呼び出し元を認証しつつ複数人で使える
HTTP + トークンレジストリ向くケースステージング・本番など複数インスタンスを横断理由ホストごとにトークンを分離しつつ切り替えられる
MCP_READ_ONLY=true向くケース障害調査専任のBotやダッシュボード理由誤操作で同期・削除が走る心配がない

よくあるつまずき

  • argocdBaseUrlを指定したのに「Missing required ArgoCD API token」と出る: 既定トークンは既定のベースURL以外には使われません。別ホストを指定するにはトークンレジストリへの登録が必要です
  • 自己署名証明書のArgoCDに繋がらない: NODE_TLS_REJECT_UNAUTHORIZED=0を環境変数に追加します。本番運用では正規の証明書に切り替えるのが望ましい対応です
  • 複数レプリカで動かすと400エラーが出る: HTTPトランスポートは既定でセッションをメモリ保持するため、セッションアフィニティのないロードバランサ配下では別Podにルーティングされて失敗します。--statelessフラグで回避できます
  • MCP_AUTH_TOKENを設定していないのに起動が失敗する: バインドアドレスをループバック以外に広げると、認証設定なしでは起動そのものを拒否する仕様です。トークンを設定するか、信頼できるプロキシ配下なら--allow-unauthenticatedを使います
  • トークンレジストリのファイルが読み込まれない: パスの誤りや権限不足でファイルが読めない場合、サーバーは既定トークンへ黙って切り替わらず起動時にエラーで止まります。設定ミスに気づかないまま別ホストへ誤ってトークンが送られる事態を避けるための、意図したフェイルクローズの挙動です

よくある質問

ArgoCD MCPサーバーはAnthropic公式のプロダクトですか

いいえ。Argo CD公式org(argoproj-labs)配下で開発されているOSSで、Anthropicの公式サーバーではありません。npm経由でnpxから直接実行でき、特別な追加インストールは不要です。開発言語はTypeScriptで、pnpmでのローカルビルドにも対応しています。

MCP_READ_ONLYと--allow-unauthenticatedはどちらを優先すべきですか

役割が違うので両方を検討します。--allow-unauthenticatedは「誰が呼べるか」を決める設定で、フロントに信頼できるプロキシがある場合にだけ使います。MCP_READ_ONLYは「呼べた後に何ができるか」を絞る設定です。読み取り専用のダッシュボード用途なら、認証は絞りつつMCP_READ_ONLY=trueも重ねておくのが安全側の構成になります。どちらか片方だけでは、認証をすり抜けられたときや読み取り専用の設定漏れがあったときに、もう一方が防波堤になりません。

Kubernetes MCPサーバーと同時に読み取り専用で運用するには

ArgoCD側はMCP_READ_ONLY=true、Kubernetes側は--read-onlyフラグとRBACのviewロールを組み合わせます。両方を読み取り専用にしておけば、GitOpsの状態確認とクラスタ内部の詳細な調査を1つの会話でこなしつつ、実際の変更は人間の承認を経たGit操作だけに限定できます。専用ServiceAccountの作り方はKubernetes MCPサーバーの権限設計で扱っています。

まとめ

ArgoCD MCPサーバーは、GitOpsのアプリケーション同期とトラブルシュートを自然言語での指示に落とし込むMCPサーバーです。個人利用ならstdio接続で十分ですが、チーム共有やマルチインスタンス構成にする際は、MCP_AUTH_TOKENとトークンレジストリを併用して権限の流出経路を塞いでください。同期先のKubernetes MCPサーバーと組み合わせれば、デプロイの同期状況からクラスタ内部の実際の状態まで一気通貫で確認できます。

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

関連する記事

Claude Code をもっと見る →