mcp-argocd

mcp-argocd

mcp-argocd は、Argo CD REST API 用の Model Context Protocol（MCP） サーバーです。AI アシスタントに 37 個のツール、7 個のリソース、7 個のプロンプトを提供し、アプリケーションのステータス確認、同期、ロールバック、ドリフトの調査、ログの読み取り、ApplicationSet、クラスター、プロジェクト、リポジトリの管理を行えます。Claude Desktop、Claude Code、Cursor、Windsurf、VS Code Copilot、および MCP 対応クライアントで動作します。書き込み可能モードと、9 個の書き込みツールがモデルに提供されない読み取り専用モード（MCP_READ_ONLY=true）のいずれかで実行できます。

Argo CD 3.3 以降に対応しています（OSS、Akuity、OpenShift GitOps など、あらゆるインストール形態に対応）。必要なのは API トークンのみで、クラスターへのアクセスは不要です。

MCP 2026-07-28 仕様（MCP 2.0 と呼ばれることもあります）に対応し、2025-11-25 クライアントとの互換性も維持しています。

FastMCP 4.x、[httpx](https://www.python-httpx.org/）、[Pydantic](https://docs.pydantic.dev/) で構築されています。

インストール： uvx mcp-argocd | PyPI | MCP Registry | 変更履歴

uvx mcp-argocd                          # with writes
MCP_READ_ONLY=true uvx mcp-argocd       # locked read-only: write tools are not listed

1クリックインストール

ヒント： その他の AI アシスタント（Claude Code、Windsurf、IntelliJ、Gemini CLI）については、**Argo CD MCP インストールゲートウェイ**をご覧ください。

# with writes
claude mcp add argocd -e ARGOCD_URL=https://argocd.example.com -e ARGOCD_TOKEN=<token> -- uvx mcp-argocd
# locked read-only
claude mcp add argocd -e MCP_READ_ONLY=true -e ARGOCD_URL=https://argocd.example.com -e ARGOCD_TOKEN=<token> -- uvx mcp-argocd

{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": ["mcp-argocd"],
      "env": {
        "ARGOCD_URL": "https://argocd.example.com",
        "ARGOCD_TOKEN": "<token>",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

# with writes
gemini mcp add -s user -e ARGOCD_URL=https://argocd.example.com -e ARGOCD_TOKEN=<token> argocd uvx mcp-argocd
# locked read-only
gemini mcp add -s user -e MCP_READ_ONLY=true -e ARGOCD_URL=https://argocd.example.com -e ARGOCD_TOKEN=<token> argocd uvx mcp-argocd

{
  "servers": {
    "argocd": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-argocd"],
      "env": {
        "ARGOCD_URL": "https://argocd.example.com",
        "ARGOCD_TOKEN": "<token>",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

# with writes
codex mcp add argocd --env ARGOCD_URL=https://argocd.example.com --env ARGOCD_TOKEN=<token> -- uvx mcp-argocd
# locked read-only
codex mcp add argocd --env MCP_READ_ONLY=true --env ARGOCD_URL=https://argocd.example.com --env ARGOCD_TOKEN=<token> -- uvx mcp-argocd

uvx mcp-argocd            # run without installing
pip install mcp-argocd    # or install into an environment

API トークンの取得

Argo CD のトークンは、apiKey 機能を持つローカルアカウント、またはプロジェクトロールから取得します。

1. argocd-cm にローカルアカウントを追加します。accounts.ci-bot: apiKey を設定します。
2. トークンを生成します。argocd account generate-token --account ci-bot --expires-in 24h
3. ARGOCD_URL と ARGOCD_TOKEN を設定します。

読み取り専用の最小 RBAC：

p, role:mcp-ro, applications, get, */*, allow
p, role:mcp-ro, logs, get, */*, allow
p, role:mcp-ro, applicationsets, get, */*, allow
p, role:mcp-ro, projects, get, *, allow
p, role:mcp-ro, clusters, get, *, allow
p, role:mcp-ro, repositories, get, *, allow

互換性

プロトコルのサポート

MCP 2026-07-28 仕様（MCP 2.0）をサポートし、2025-11-25 のクライアントとの互換性も維持しています。 FastMCP 4.x を基盤として構築されています。回帰テストでは、2026-07-28 に固定したメモリ内 MCP クライアントを使って、全 37 個のツールを一覧表示します。sse トランスポートは 2026-07-28 仕様で非推奨になっていますが、引き続き動作し、警告を出力します。サーバーは roots、sampling、logging、elicitation、resource subscriptions を使用しません。

エラー結果

想定される失敗（アプリが見つからない（404）、権限が拒否される（403）、読み取り専用ガードに到達した書き込み）は、成功エンベロープではなく、isError: true を含むツール結果を返します。（読み取り専用に固定されている場合、書き込みツールは非表示になるため、呼び出すと Unknown tool エラーが返されます。以下のエンベロープはガード自体の応答であり、クライアントが何らかの方法で書き込みツールに到達した場合にのみ返されます。）本文は、{"error", "status_code"?, "body"?, "hint"?} という JSON オブジェクトです。hint は、該当する場合に修正方法を示します。本文は結果の整形済みテキストコンテンツです。厳格な MCP クライアント（TypeScript SDK）は、isError が true の場合でも structuredContent をツールの outputSchema に照らして検証し、そうでないとエラーを拒否するため、結果には structuredContent が含まれません。 想定外のバグも isError: true になりますが、TypeName: message 形式のテキストと、ログに記録されたトレースバックが含まれます。成功した結果には、整形済みテキストとともに同じ JSON オブジェクトが structuredContent として含まれるため、クライアントはいずれかを読み取れます。ツールは outputSchema を公開しません。ペイロードは型指定なしで上流のフィールドをそのまま渡します。型付きスキーマは、ツールごとに output_schema= を指定してオプトインできます。

ツール（37 個）

リソース（7）

サーバーは、厳選された GitOps のルールとガイドを MCP リソースとして公開します。

• resource://rules/sync-safety — 同期の安全性に関するルール。
• resource://rules/rollback — ロールバックのルール。
• resource://rules/gitops-change-flow — GitOps の変更フロー。
• resource://rules/applicationsets — ApplicationSet のルール。
• resource://guides/status-triage — ステータス切り分けガイド。
• resource://guides/rbac — RBAC と権限エラー。
• resource://guides/api-token-setup — API トークンの設定。

プロンプト（7）

サーバーは MCP プロンプトを提供します。クライアントがスラッシュコマンドとして表示する、複数のツールを組み合わせたワークフローテンプレートです。

• triage_application — Degraded または OutOfSync のアプリケーションを診断します。
• diagnose_sync_failure — 前回の同期が失敗した理由を分類します。
• review_drift — OutOfSync のアプリを確認し、修正方法を提案します。
• safe_sync — 同期ウィンドウを確認し、ドライランを実行してから同期し、完了を待ちます。
• rollback_application — 自動同期を確認してからロールバックします。
• fleet_status — Synced／Healthy ではないクラスターとアプリを報告します。
• inspect_applicationset — 生成されたアプリと既存のアプリを比較します。

使用例

• トリアージ：「payments が Degraded なのはなぜですか？」を実行すると、triage_application が実行されます。アプリの状態、正常でないノード、警告イベントを確認し、その後ポッドのログを確認します。
• ドリフト：「prod でドリフトしているものは何ですか？」を実行すると、review_drift が実行されます。OutOfSync のアプリを一覧表示し、それぞれの差分を表示します。
• 安全な同期：「web を安全に同期して」を実行すると、safe_sync が実行されます。同期ウィンドウを確認し、ドライランを実行してから同期し、完了を待ちます。
• ロールバック：「api を最後に正常だったデプロイに戻して」を実行すると、rollback_application が実行されます。最初に自動同期を確認します。
• フリート：「クラスターの状態を表示して」を実行すると、fleet_status が実行されます。クラスターと、正常でないアプリを表示します。

セキュリティに関する考慮事項

• トークンのスコープ：ワークフローに必要な最小限の RBAC を使用してください。読み取り専用ロールには applications, get と logs, get が必要です。
• 読み取り専用モード：管理下の起動設定で MCP_READ_ONLY=true（または ARGOCD_READ_ONLY=true）を設定すると、サーバーはロックされた状態で起動します。書き込みツール 9 個と書き込みワークフローのプロンプトは一覧に表示されず、それらを呼び出すと「Unknown tool」が返され、ガードは到達した書き込み要求をすべて拒否します。実行時にロックを解除する方法はありません。別のソースからの false、.env ファイル、ツール引数でも解除されません。false／0／no／off／空以外の値はロックを有効にし、--read-only でできるのはロックを強化することだけです。ロックの強度は起動設定に依存します。ユーザーが編集できない場所（Claude Code の managed-mcp.json などの管理対象 MCP 設定、コンテナー、k8s または systemd の環境変数、ホスト型 HTTP デプロイなど）で設定してください。サーバーを自分で起動するユーザーは、その環境を制御できます。読み取り専用の Argo CD RBAC ロール（applications, get、logs, get）と組み合わせてください。
• SSL 検証：デフォルトで有効です。信頼できるネットワーク内の自己署名証明書に限り、無効にしてください。
• シークレットの除去：リポジトリー、クラスター、プロジェクトのペイロードから、認証情報、クラスターの config、ロールの jwtTokens が除去されます。full=True の場合も同様です。
• MCP ツールのアノテーション：すべてのツールで readOnlyHint、destructiveHint、idempotentHint を宣言しています。
• 認証情報の保存なし：サーバーは起動時に環境変数からトークンを読み取り、永続化しません。
• 破壊的なツール：argocd_sync_application、argocd_rollback_application、argocd_terminate_operation、argocd_delete_application、argocd_run_resource_action、argocd_delete_resource。

権限

CLI とトランスポートのオプション

uvx mcp-argocd                                   # stdio (default)
uvx mcp-argocd --transport streamable-http --port 9000
uvx mcp-argocd --transport sse                   # deprecated; prints a warning
uvx mcp-argocd --read-only --insecure

HTTP トランスポートは、オーナーの Argo CD トークンを使ってすべてのツールを提供します。ポートに到達できるユーザーであれば誰でも利用できます。Host／Origin による保護は認証ではないため、ループバック以外のホストにバインドする場合はベアラートークンが必要です。ARGOCD_HTTP_BEARER_TOKEN を設定してください（16 文字以上。クライアントは Authorization: Bearer <token> を送信します）。設定しない場合、サーバーはループバック以外のホストでの起動を拒否します。

ARGOCD_HTTP_BEARER_TOKEN=$(openssl rand -hex 32) \
  uvx mcp-argocd --transport streamable-http --host 0.0.0.0 --port 9000

Docker

イメージはデフォルトで読み取り専用（MCP_READ_ONLY=true）にロックされています。書き込みを許可するには、-e MCP_READ_ONLY=false を渡してください。

docker build -t mcp-argocd .

# stdio, locked read-only (the image default)
docker run --rm -i \
  -e ARGOCD_URL=https://argocd.example.com \
  -e ARGOCD_TOKEN=<token> \
  mcp-argocd

イメージは root 以外のユーザーとして実行され、デフォルトでは stdio を使用します。HTTP 経由で提供するには、ARGOCD_HTTP_BEARER_TOKEN を設定したうえで、--transport streamable-http --host 0.0.0.0 を渡してください。

FAQ

mcp-argocd は MCP 2026-07-28（MCP 2.0）に対応していますか？ はい。MCP 2.0 と呼ばれることの多い MCP 2026-07-28 仕様に対応し、2025-11-25 のクライアントとの互換性も維持しています。

argoproj-labs/mcp-for-argocd とはどう違いますか？ argoproj-labs/mcp-for-argocd は、15 個のツールを備えた公式の TypeScript サーバーです。mcp-argocd は、デフォルトで軽量なペイロードを使用する 37 個のツールに加え、差分、ロールバック、終了、操作の完了待機、ApplicationSet のドライラン、RBAC エラーのヒントを追加しています。

どの Argo CD バージョンで動作しますか？ Argo CD 3.3 以降です。ほとんどのツールは 2.x でも動作しますが、run_resource_action のみ 3.x のエンドポイントを使用します。

kubectl やクラスターの認証情報は必要ですか？ いいえ。ベアラートークンを使用して HTTPS 経由で Argo CD API に接続します。クラスターに直接アクセスすることはありません。

アシスタントが同期や削除を行えないように、mcp-argocd を読み取り専用で実行できますか？ はい。MCP_READ_ONLY=true（または ARGOCD_READ_ONLY=true）を設定して起動してください。9 個の書き込みツールと書き込みワークフローのプロンプトは一覧に表示されなくなるため、モデルから見えなくなります。これらのツールを呼び出すと「Unknown tool」が返され、プロセスの実行中に書き込みを再び有効にすることはできません。ユーザーが変数を設定せずにサーバーを起動できないよう、管理対象の MCP 設定、コンテナーや systemd の環境変数、ホスト型デプロイなど、自分で管理できる起動方法で設定してください。

どのトークンが必要ですか？ ARGOCD_TOKEN にベアラートークンが必要です。apiKey 機能を持つローカルアカウントで生成するか、プロジェクトロールトークンを使用してください。また、ARGOCD_AUTH_TOKEN と ARGOCD_API_TOKEN も読み取ります。

存在するアプリに対して 403 が返されるのはなぜですか？ project を指定しない場合、存在しないアプリに対して Argo CD は 403 を返します。実際の 404 を取得するには、project を渡してください。

1 つのリソースだけを同期できますか？ はい。argocd_sync_application に [group:]kind:name[/namespace] セレクターを指定して、resources を渡してください。

ロールバックできますか？ はい。履歴 ID を指定して argocd_rollback_application を使用してください。自動同期が有効な間はロールバックを拒否し、無効にする方法を案内します。

レスポンスを小さく保つにはどうしていますか？ すべてのツールはデフォルトで軽量なペイロードを返し、リストはクライアント側でページ分割します。生のペイロードを取得するには、full=True を渡してください。

どのトランスポートに対応していますか？ stdio、streamable-http、sse です。sse は 2026-07-28 仕様で非推奨になりましたが、引き続き動作します。

インストール方法を教えてください。 uvx mcp-argocd を実行するか、MCP クライアントの設定に追加してください。

関連する MCP サーバー

• mcp-gitlab — GitLab 連携（83 個のツール、7 個のリソース、6 個のプロンプト）
• mcp-atlassian-extended — Jira と Confluence の連携（22 個のツール、15 個のリソース、5 個のプロンプト）
• mcp-coda — Coda 連携（53 個のツール、12 個のリソース、5 個のプロンプト）

開発

git clone https://github.com/vish288/mcp-argocd.git
cd mcp-argocd
uv sync --all-extras

uv run pytest --cov
uv run ruff check .
uv run ruff format --check .

ライセンス

MIT — LICENSE を参照してください。