--- title: "ArgoCD MCPの使い方：mcp-for-argocdでAIエージェントにSync・ログ調査を任せる設定と権限設計【v0.9.0】" url: "https://www.issoh.co.jp/tech/details/18567/" published: 2026-10-19 updated: 2026-10-19 categories: ["インフラ・クラウド"] publisher: "株式会社一創" --- # ArgoCD MCPの使い方：mcp-for-argocdでAIエージェントにSync・ログ調査を任せる設定と権限設計【v0.9.0】 ArgoCD MCPは、Argo CDのAPIをMCP（Model Context Protocol）のツールとしてAIエージェントへ渡す仕組みです。代表的な実装はargoproj-labsが管理する `mcp-for-argocd`（npmパッケージ名は `argocd-mcp`）で、2026年10月時点の最新版はv0.9.0です。この記事では、16本あるツールの内訳、Cursor・VS Codeからstdioで接続する設定、AIエージェント専用アカウントとRBACで操作範囲を絞る方法、v0.8.0で見つかったCVSS 10.0の脆弱性とHTTPモードの安全な公開手順まで、YAMLとコマンド付きで整理します。 ## まとめ：ArgoCD MCPは読み取り専用・専用アカウント・stdioで始める 最初の構成は3点で決まります。`MCP_READ_ONLY=true` で変更系の5ツールを登録させないこと、Argo CDに `apiKey` だけを持つAI専用のローカルアカウントを作り、RBACで `get` と `logs` に絞ること、そしてHTTPではなくstdioで各自のマシンから起動することです。この形なら、AIにできるのはApplicationの状態・イベント・ログの読み取りまでになります。 Syncを任せるのは、dev環境のprojectに限ってRBACで `sync` を許してからにしてください。HTTPモードで複数人に共有するなら、v0.9.0未満は使わず、`MCP_AUTH_TOKEN` を必ず設定します。本番のApplicationの作成・更新・削除は、MCPではなくGitのPull Requestに残すのが前提です。 ## mcp-for-argocdがAIエージェントへ公開する16ツールと提供元 Argo CDやGitOpsの仕組み自体は[ArgoCDとは？GitOpsの仕組みとインストール・Sync設定をコード付きで解説](https://www.issoh.co.jp/tech/details/15438/)で扱いました。ここではMCPサーバー側の中身を確認します。 ### Akuityが寄贈しargoproj-labsへ移ったMCPサーバーの版と系譜 [argoproj-labs/mcp-for-argocd](https://github.com/argoproj-labs/mcp-for-argocd)は、Apache-2.0で公開されているTypeScript製のMCPサーバーです。READMEのCreditsには、Akuity社のメンバー4人が作成して寄贈したと書かれています。v0.3.0（2025年8月）まではリリースノートのリンク先が `akuity/argocd-mcp` で、v0.4.0で「Akuityへの参照を削除」したため、検索結果にAkuity版とargoproj-labs版が両方出てきます。中身は同じ系譜です。 2026年10月19日時点の最新リリースは[v0.9.0（2026-08-11公開）](https://github.com/argoproj-labs/mcp-for-argocd/releases/tag/v0.9.0)です。v0.6.0で `list_clusters`、v0.7.0でstatelessモード、v0.8.0で呼び出しごとの接続先上書き、v0.9.0で `get_appproject` と後述のセキュリティ修正が入りました。MCPの規格そのものは[MCPとは？AIと外部ツールをつなぐ標準規格とMCPサーバーの仕組み・作り方を解説](https://www.issoh.co.jp/column/details/12966/)を参照してください。 ### 読み取り11本と変更5本に分かれるツールの内訳と運用時の使い道 v0.9.0の `src/server/server.ts` を読むと、ツールは常に登録される読み取り系11本と、読み取り専用モードでないときだけ登録される変更系5本に分かれています。 | 区分 | 本数 | AIに頼む作業の例 | | ------------- | -- | ---------------- | | 一覧・状態（読み取り） | 4本 | OutOfSyncのアプリを探す | | リソース（読み取り） | 3本 | Degradedの原因を特定 | | ログ・イベント（読み取り） | 3本 | Podのログとイベントを要約 | | 操作候補（読み取り） | 1本 | 実行できるアクションの列挙 | | Application変更 | 3本 | 作成・更新・削除 | | Sync・アクション実行 | 2本 | 再Sync、再起動など | 一覧・状態は `list_applications`・`list_clusters`・`get_application`・`get_appproject`、リソースは `get_application_resource_tree`・`get_application_managed_resources`・`get_resources`、ログ・イベントは `get_application_workload_logs`・`get_application_events`・`get_resource_events`、操作候補は `get_resource_actions` です。変更系は `create_application`・`update_application`・`delete_application` と、`sync_application`・`run_resource_action` の5本になります。 `sync_application` は `dryRun`・`prune`・`revision`・`syncOptions` を、`delete_application` は `cascade` と `propagationPolicy` を引数に取ります。つまりAIの判断ひとつで、任意のリビジョンへのSyncや配下リソースごとの削除まで呼べる作りです。既定ではこの5本も有効になっています。 ## npxのstdio起動でCursor・VS CodeからArgo CDへ接続する手順 個人の端末から使うなら、stdioで起動するのがいちばん手間がかかりません。待ち受けポートを開かないため、ネットワーク側の設定が要らないからです。 ### Node.js 18以上とAPIトークンで動かすmcp.jsonの設定例 前提はNode.js 18以上と、APIにアクセスできるArgo CD、そしてAPIトークンです。VS Codeならプロジェクト直下の `.vscode/mcp.json` に次のように書きます。READMEの例は `@latest` ですが、版の固定を勧めます。 ``` { "servers": { "argocd-mcp": { "type": "stdio", "command": "npx", "args": ["argocd-mcp@0.9.0", "stdio"], "env": { "ARGOCD_BASE_URL": "https://argocd.example.com", "ARGOCD_API_TOKEN": "${input:argocd_token}", "MCP_READ_ONLY": "true" } } }, "inputs": [ { "type": "promptString", "id": "argocd_token", "description": "Argo CD API token", "password": true } ] } ``` Cursorは `.cursor/mcp.json`、Claude Desktopは `claude_desktop_config.json` の `mcpServers` キーの下へ同じ内容を書きます。`inputs` を使うと、トークンを平文で残さず起動時に入力させられます。`MCP_READ_ONLY` は文字列の `true` と一致したときだけ有効になるので、引用符で囲んでください。 ### 自己署名証明書でNODE\_TLS\_REJECT\_UNAUTHORIZEDを常用しない理由 社内CAの証明書でArgo CDを公開している環境では、接続時にTLS検証で失敗します。READMEは回避策として `NODE_TLS_REJECT_UNAUTHORIZED=0` を挙げていますが、同時に開発環境以外では使わないよう警告しています。これはNode.jsプロセス全体の証明書検証を止める設定で、トークンを送る通信の相手を確かめなくなるためです。 本番相当の環境では、Node.jsの `NODE_EXTRA_CA_CERTS` に社内CAの証明書ファイルを指定して信頼させるほうが筋の通った対処です。APIトークンはArgo CDのフルアクセスに近い権限を持ちうるので、通信先の検証を外した状態で使い続けないでください。 ## AIエージェント専用のArgo CDアカウントとRBACで操作範囲を絞る設定 MCPサーバーが何をできるかは、渡したAPIトークンの権限で決まります。adminのトークンを渡すと、AIもadminとして振る舞います。 ### argocd-cmにapiKeyだけを持つローカルアカウントを作る手順 [Argo CDのユーザー管理](https://argo-cd.readthedocs.io/en/stable/operator-manual/user-management/)では、`argocd-cm` に `accounts.<名前>` を足すとローカルアカウントを作れます。能力は `apiKey`（トークン発行）と `login`（UIログイン）の2つで、AI用には `apiKey` だけを付けます。 ``` apiVersion: v1 kind: ConfigMap metadata: name: argocd-cm namespace: argocd labels: app.kubernetes.io/name: argocd-cm app.kubernetes.io/part-of: argocd data: accounts.ai-agent: apiKey ``` 適用後、トークンを発行します。`argocd account generate-token` の `--expires-in` は既定で無期限（`0s`）なので、期限と識別子を必ず付けます。 ``` argocd account generate-token --account ai-agent --expires-in 720h --id mcp-2026-10 ``` UIの操作者と同じアカウントを流用しないのは、Sync操作の実行者やイベントの記録で「AIが行った操作」を区別するためです。漏えいした場合も、このアカウントのトークンだけを失効させれば済みます。 ### argocd-rbac-cmでget・logsとdev環境のsyncだけを許す例 [RBACの設定ページ](https://argo-cd.readthedocs.io/en/stable/operator-manual/rbac/)は、`applications` に `get`・`sync`・`action`・`override` など、`logs` に `get` のアクションを定義しています。`policy.<任意>.csv` というキーを足すと既存の `policy.csv` の後ろに連結されるので、既存の権限を書き換えずに追加できます。 ``` apiVersion: v1 kind: ConfigMap metadata: name: argocd-rbac-cm namespace: argocd data: policy.ai-agent.csv: | p, role:ai-reader, applications, get, */*, allow p, role:ai-reader, logs, get, */*, allow p, role:ai-reader, projects, get, *, allow p, role:ai-reader, clusters, get, *, allow p, role:ai-reader, applications, sync, dev/*, allow g, ai-agent, role:ai-reader ``` 見落としやすいのがリビジョン指定のSyncです。`sync_application` は `revision` を受け取りますが、Argo CDは既定でリビジョン指定のSyncを `override` とみなしません。`argocd-cm` 側で `application.sync.requireOverridePrivilegeForRevisionSync` を `'true'` にすると、Applicationに書かれたリビジョン以外へのSyncに `override` 権限が要るようになり、AIが古いコミットへ戻す操作を止められます。 ``` kubectl -n argocd patch cm argocd-cm --type merge \ -p '{"data":{"application.sync.requireOverridePrivilegeForRevisionSync":"true"}}' ``` もう1点、`policy.default` に `role:readonly` を入れていると、認証済みの全員にその権限が付き、AI用アカウントも例外ではありません。適用前に次のコマンドで、意図した操作だけが通るかを確かめます。 ``` argocd admin settings rbac can ai-agent sync applications 'prod/shop-api' --namespace argocd argocd admin settings rbac can ai-agent sync applications 'dev/shop-api' --namespace argocd ``` 1行目が `No`、2行目が `Yes` になれば想定どおりです。 ### MCP\_READ\_ONLYで変更系5ツールを外しても残る情報の露出 `MCP_READ_ONLY=true` を付けると、変更系の5本は登録自体がされません。AIのツール一覧に現れないため、RBACで拒否する場合と違って、呼び出しを試みて403が返る無駄も起きません。 ただし読み取りだけでも、外へ出る情報は少なくありません。`get_application_workload_logs` はPodのログを、`get_resources` は管理下リソースのマニフェストをそのままモデルへ渡します。ログに顧客のメールアドレスやリクエスト本文が出るアプリなら、外部のLLMへ送ってよいかを先に判断してください。気になる場合はRBACから `logs, get` の行を外し、ログ調査だけ人が行う分担にします。 ## HTTPモードで共有するときのv0.9.0のバインド制限と認証 チームで1台のMCPサーバーを共有したい場合はHTTP（Streamable HTTP）モードを使います。トランスポートの違いは[Streamable HTTPとは？MCPのトランスポートとSSEの違い](https://www.issoh.co.jp/tech/details/6580/)で整理しました。 ### v0.8.0のCVSS 10.0脆弱性GHSA-rp45-5x3v-48mrの影響範囲 2026年8月11日に公開された[GHSA-rp45-5x3v-48mr](https://github.com/argoproj-labs/mcp-for-argocd/security/advisories/GHSA-rp45-5x3v-48mr)は、深刻度Critical、CVSS 3.1のスコア10.0です。影響を受けるのは `argocd-mcp` 0.8.0で、0.9.0で修正されました。 原因は2つあります。HTTPトランスポートが全インターフェースで待ち受けていたこと、そして呼び出し元を認証せず、サーバーの `ARGOCD_API_TOKEN` でツールを実行していたことです。勧告は、攻撃者が自分のGitリポジトリを指すApplicationを `create_application` で作り、`sync_application` で同期させる手順を示しています。stdioだけで使っていた場合は対象外ですが、http・sseで動かしていたなら、Argo CD側に見覚えのないApplicationが無いか確かめてください。Argo CD本体の脆弱性は別物で、[Argo CDの脆弱性一覧と対処](https://www.issoh.co.jp/tech/details/18560/)にまとめています。 ### MCP\_BIND\_ADDRESSとMCP\_AUTH\_TOKENでポートを公開する起動例 v0.9.0から、HTTPとSSEは既定で `127.0.0.1` だけで待ち受けます。それ以外のアドレスへ広げるときは、`MCP_AUTH_TOKEN` か `--allow-unauthenticated` のどちらかが無いと起動自体が失敗する仕様です。コンテナでポートを公開する例は次のとおりです。 ``` docker run -p 3000:3000 \ -e ARGOCD_BASE_URL=https://argocd.example.com \ -e ARGOCD_API_TOKEN="$ARGOCD_API_TOKEN" \ -e MCP_BIND_ADDRESS=0.0.0.0 \ -e MCP_AUTH_TOKEN="$MCP_INBOUND_TOKEN" \ -e MCP_READ_ONLY=true \ ghcr.io/argoproj-labs/mcp-for-argocd:0.9.0 http --allowed-host-header mcp.internal.example.com ``` ここで混同しやすいのが2種類のトークンです。`ARGOCD_API_TOKEN` はMCPサーバーがArgo CDへ名乗るための送信側の資格情報で、呼び出し元の認証には一切使われません。`MCP_AUTH_TOKEN` を設定すると、全リクエストに必要なのが `Authorization: Bearer` です。[SECURITY.md](https://github.com/argoproj-labs/mcp-for-argocd/blob/main/SECURITY.md)は、このトークンが利用者ごとの識別ではなく共有の秘密だと明記しています。人によって触れる範囲を変えたいなら、インスタンスを分け、それぞれ別のArgo CDアカウントと読み取り専用設定を持たせます。 ### 複数のArgo CDを扱うトークンレジストリと接続先の解決順 全ツールは任意の引数 `argocdBaseUrl` を受け取り、呼び出しごとに接続先のArgo CDを変えられます。危ないのは、この値がツール呼び出し、つまりモデルの出力から来る点です。プロンプトインジェクションで攻撃者のホストを指定されても、トークンが送られない設計になっています。 具体的には、既定のトークンは既定の `ARGOCD_BASE_URL` にしか送られません。別のインスタンスを使うには、`ARGOCD_TOKEN_REGISTRY_PATH` で指すJSONファイルに接続先とトークンの組を登録します。 ``` [ { "baseUrl": "https://argocd-stg.example.com", "token": "" }, { "baseUrl": "https://argocd-prod.example.com", "token": "" } ] ``` 登録の無いURLを指定された呼び出しは、Argo CDへ通信せずにエラーで終わります。ファイルが壊れていたり読めなかったりすると、起動時に失敗する作りです。トークンを環境変数に置かないための仕組みなので、KubernetesのSecretをボリュームでマウントして渡します。 ### statelessモードでKubernetes上のレプリカを増やす条件 HTTPモードは既定で接続ごとにセッションIDを発行し、メモリ上に保持します。スティッキーセッションの無いロードバランサの裏で複数レプリカを動かすと、別のPodに届いたリクエストの応答は400です。`http --stateless` で起動すれば、どのレプリカでも処理できます。 stateless時はArgo CDの資格情報を毎リクエストで環境変数かヘッダから解決し、`GET /mcp` と `DELETE /mcp` は405を返します。ヘルスチェックには認証不要の `GET /healthz` を使います。同じPod内のサイドカーからは `127.0.0.1` のまま届くため、認証プロキシをサイドカーで立てる構成ならバインドを広げる必要もありません。 ## ArgoCD MCPに任せる操作と人のレビューに残す操作の線引き ここからは判断を言い切ります。ArgoCD MCPは「調べる道具」として入れ、「変える道具」としては限定的に使います。 ### 障害調査の読み取りで効く場面とsync\_applicationを渡さない条件 効果が出やすいのは、デプロイ後にApplicationがDegradedやOutOfSyncになったときの一次調査です。異常なアプリを探し、リソースツリーで原因のPodを特定し、イベントとログを要約させる流れは、読み取り系のツールだけで完結します。 `sync_application` を渡さないのは次の条件のどれかに当たる場合です。Applicationが本番クラスターを向いている、`prune` を伴うSyncが日常的に起きる、変更の承認記録をGitのPull Requestで残す決まりがある。dev環境で再Syncを繰り返すだけの用途なら、RBACで `dev/*` に限って許せば十分です。 ### Gitを正とするGitOpsとMCP経由のApplication変更が衝突する理由 `create_application` と `update_application` は、Argo CDのAPIへ直接Applicationを書き込みます。Gitを正とする運用では、この書き込みはGitに無い変更をクラスターに入れる操作です。App of AppsやApplicationSetでApplication自体をGitから生成している場合、MCP経由の変更は、ApplicationSetコントローラーや親Applicationの自動同期によってGit側の値へ戻されます。生成の仕組みは[ArgoCD ApplicationSetの使い方](https://www.issoh.co.jp/tech/details/18565/)で解説しました。 結論として、本番のApplication定義の変更は、AIにPull Requestを作らせて人がレビューする経路に残し、MCPには読み取りとdev環境のSyncだけを渡す構成を勧めます。この分担はGitOpsの原則そのもので、前提は[GitOpsとは：4原則とPush型との違い、Argo CD・Fluxの最小構成YAML](https://www.issoh.co.jp/tech/details/18553/)にまとめています。MCPサーバーごとに開けるツールの範囲を決める考え方は[Terraform MCP Serverのtoolsetの権限設計](https://www.issoh.co.jp/tech/details/16551/)とも共通です。Argo CDの運用にAIエージェントを組み込む設計や、既存のデプロイ手順のGitOps化を相談したい場合は、[DevOps・CI/CD導入支援](https://www.issoh.co.jp/service/system/devops/)で権限設計から引き継ぎまで対応しています。 ## よくある質問 ArgoCD MCPを導入するときに出やすい疑問に、READMEとArgo CD公式ドキュメントの記述をもとに答えます。 ### Akuity版のargocd-mcpとargoproj-labs版はどちらを使えばよいですか？ 同じプロジェクトです。Akuityのメンバーが作った `akuity/argocd-mcp` がargoproj-labsへ寄贈され、現在のリポジトリは `argoproj-labs/mcp-for-argocd` です。npmのパッケージ名は `argocd-mcp` のまま変わっていません。新規に入れるなら、v0.9.0以降をargoproj-labsのリポジトリかnpmから取得してください。名前の似た別作者の実装もあるため、作者とリポジトリを確かめてから使います。 ### ArgoCD MCPは無料で使えますか？ MCPサーバー自体はApache-2.0のオープンソースで、npmパッケージとコンテナイメージ（ghcr.ioとquay.io）が無料で公開されています。Argo CDもOSSなので、費用が発生するのはMCPクライアント側で使うLLMの利用料と、商用のマネージドArgo CDを契約している場合のその料金です。 ### APIトークンをツールの引数で渡せますか？ 渡せません。READMEは、APIトークンを `x-argocd-api-token` ヘッダか環境変数 `ARGOCD_API_TOKEN` からのみ読むと明記しています。ツール引数に入れると、プロンプトやモデルのコンテキスト、ツール呼び出しのログに残ってしまうためです。接続先URLだけは `argocdBaseUrl` 引数で変えられますが、既定以外の接続先にはトークンレジストリへの登録が必要です。 ### Argo CDのproject roleのトークンをMCPに使えますか？ 使えます。`argocd proj role create-token` で発行したJWTは、そのprojectのApplicationに限った権限になります。ただしproject roleに書けるのは `applications`・`applicationsets`・`logs`・`exec` のポリシーだけです。`list_clusters` や `get_appproject` のようにproject外のリソースを読むツールは権限不足になる前提で使ってください。[Projectsのページ](https://argo-cd.readthedocs.io/en/stable/user-guide/projects/)のとおり、このトークンも既定は無期限なので `-e` で期限を付けます。 ### Claude CodeなどVS Code以外のクライアントでも動きますか？ 動きます。`npx argocd-mcp@0.9.0 stdio` を起動コマンドとして登録できるMCPクライアントなら種類を問いません。READMEの設定例はCursor・VS Code・Claude Desktopの3つですが、CLI型のクライアントでも、環境変数 `ARGOCD_BASE_URL`・`ARGOCD_API_TOKEN`・`MCP_READ_ONLY` を渡せば同じ構成になります。 ## 関連記事 - [ArgoCDとは？GitOpsの仕組みとインストール・Sync設定をコード付きで解説](https://www.issoh.co.jp/tech/details/15438/)：MCPサーバーの接続先となるArgo CD本体の仕組み - [ArgoCD ApplicationSetの使い方：List・Cluster・Git・Matrixジェネレーターで複数クラスタへ展開するYAML【3.5系】](https://www.issoh.co.jp/tech/details/18565/)：Gitから生成したApplicationとMCP経由の変更の関係 - [GitOpsとは：4原則とPush型との違い、Argo CD・Fluxの最小構成YAML【2026年10月】](https://www.issoh.co.jp/tech/details/18553/)：AIに渡す操作を線引きする前提の運用モデル - [Argo CDの脆弱性一覧と対処：2026年10月のCritical4件と修正版3.5.4・3.4.10・3.3.15への更新手順](https://www.issoh.co.jp/tech/details/18560/)：MCPサーバーの接続先となる本体の版の確認 - [MCPとは？AIと外部ツールをつなぐ標準規格とMCPサーバーの仕組み・作り方を解説](https://www.issoh.co.jp/column/details/12966/)：MCPの規格とサーバーの役割 - [Terraform MCP Serverとは？導入手順とtoolsetの権限設計を実装目線で解説](https://www.issoh.co.jp/tech/details/16551/)：IaC側のMCPサーバーで開けるツールを絞る設計 --- 出典: [ArgoCD MCPの使い方：mcp-for-argocdでAIエージェントにSync・ログ調査を任せる設定と権限設計【v0.9.0】]()（株式会社一創）