Argo CD MCP Server

Argo CD MCP サーバー

Argo CD 向けの Model Context Protocol (MCP) サーバーの実装です。AI アシスタントが自然言語を通じて Argo CD アプリケーションを操作できるようにします。このサーバーにより、stdio および HTTP ストリームトランスポートプロトコルを介して、Visual Studio Code やその他の MCP クライアントとシームレスに統合できます。

---

機能

• トランスポートプロトコル：さまざまなクライアントと柔軟に統合できるよう、stdio と HTTP ストリームの両方のトランスポートモードをサポートします
• Argo CD API との完全な統合：Argo CD のリソースや操作に包括的にアクセスできます
• AI アシスタント対応：AI アシスタントが自然言語で Argo CD を操作するためのツールがあらかじめ設定されています

利用可能なツール

このサーバーは、次の Argo CD 管理ツールを提供します。

クラスター管理

• list_clusters：ArgoCD に登録されているすべてのクラスターを一覧表示します

プロジェクト管理

• get_appproject：特定の AppProject（プロジェクト）の詳細情報を取得します

アプリケーション管理

• list_applications：すべてのアプリケーションを一覧表示し、絞り込みます
• get_application：特定のアプリケーションの詳細情報を取得します
• get_application_events：特定のアプリケーションのイベントを取得します
• create_application：新しいアプリケーションを作成します
• update_application：既存のアプリケーションを更新します
• delete_application：アプリケーションを削除します
• sync_application：アプリケーションの同期操作を開始します

リソース管理

• get_application_resource_tree：特定のアプリケーションのリソースツリーを取得します
• get_application_managed_resources：特定のアプリケーションの管理対象リソースを取得します
• get_resources：アプリケーションが管理するリソースのマニフェストを取得します
• get_application_workload_logs：アプリケーションのワークロード（Pod、Deployment など）のログを取得します
• get_resource_events：アプリケーションが管理するリソースのイベントを取得します
• get_resource_actions：リソースで利用可能なアクションを取得します
• run_resource_action：リソースに対してアクションを実行します

インストール

前提条件

• Node.js（v18 以上を推奨）
• pnpm パッケージマネージャー（開発用）
• API アクセスが可能な Argo CD インスタンス
• Argo CD API トークン（手順についてはドキュメントを参照してください）

Cursor での使用方法

1. MCP サポートに関する 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>"
      }
    }
  }
}

2. Agent モードで会話を開始して、MCP を使用します。

VSCode での使用

1. VS Code で MCP サーバーを使用するためのドキュメントに従って、プロジェクト内に .vscode/mcp.json ファイルを作成します：

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

2. VS Code で MCP をサポートする AI アシスタントとの会話を開始します。

Claude Desktop での使用

1. Claude Desktop での MCP に関するドキュメントに従って、claude_desktop_config.json 構成ファイルを作成します：

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

2. Claude Desktop の設定でこの構成ファイルを使用するように構成します。

自己署名証明書

Argo CD インスタンスが自己署名証明書、またはプライベート認証局 (CA) の証明書を使用している場合は、構成に次の環境変数を追加する必要があるかもしれません：

"NODE_TLS_REJECT_UNAUTHORIZED": "0"

これは、自己署名証明書、またはシステムの証明書ストアで信頼されていないプライベート CA の証明書を使用して Argo CD インスタンスに接続する際に、Node.js の TLS 証明書検証を無効にします。

警告: SSL 検証を無効にするとセキュリティが低下します。この設定は開発環境でのみ、またはセキュリティへの影響を理解している場合にのみ使用してください。

ArgoCD 認証情報の提供

サーバーは ベース URL と API トークンを使用して ArgoCD に接続します。

API トークン — ヘッダー / 環境変数のみ (必須)

ArgoCD の API トークンはシークレットであり、トランスポート層からのみ読み取られ、ツール呼び出しの引数から読み取られることは決してありません：

• HTTP ヘッダー (HTTP トランスポートのみ)：x-argocd-api-token。
• 環境変数：ARGOCD_API_TOKEN (すべてのトランスポート)。

このトークンはアウトバウンド専用です。つまり、このサーバーが ArgoCD に対して認証を行うものであり、インバウンドの呼び出し元を認可することは決してありません。リスナーに到達できるユーザーについては、ネットワーク公開を参照してください。

これはデフォルトのトークンです。トークンレジストリが構成されていない限り必須です。HTTP トランスポートでは、トークンを提供しない接続 (ヘッダーも環境変数もなし) は 400 Bad Request で拒否されますが、レジストリが構成されている場合は、各呼び出しが独自の レジストリトークンを解決するため、トークンなしの接続が許可されます。トークンをツールの引数から除外しておくことで、トークンがプロンプト、モデルコンテキスト、ツール呼び出しログに入り込まないことが保証されます。

ベース URL — ヘッダー / 環境変数、または呼び出しごとの引数

ベース URL は、セッションレベルで指定できます (サーバーの起動時、または HTTP クライアントの接続時に一度解決されます)：

• HTTP ヘッダー (HTTP トランスポートのみ)：x-argocd-base-url。
• 環境変数：ARGOCD_BASE_URL (すべてのトランスポート)。

さらに、すべてのツールはオプションの argocdBaseUrl 引数を受け付けます：

• セッションのデフォルトベース URL が存在する場合、argocdBaseUrl はオプションであり、その 1 回の呼び出しでデフォルトを上書きします。
• セッションのデフォルトベース URL が構成されていない場合 (ヘッダーと環境変数の両方が存在しない)、argocdBaseUrl は必須です。これなしで呼び出すとエラーが返されます。

トークンレジストリ — ベース URL ごとのトークン（複数インスタンス）

それぞれ独自のトークンを持つ複数の ArgoCD インスタンスを対象にするには、トークンレジストリを設定します。トークンはシークレットであるため、レジストリは環境変数ではなく JSON ファイルから読み込まれます。ARGOCD_TOKEN_REGISTRY_PATH にファイル（マウントされた Kubernetes シークレットなど）を指定してください。これにより、トークンがプロセス環境、クラッシュダンプ、子プロセスへの継承に含まれるのを防げます。

ARGOCD_TOKEN_REGISTRY_PATH=/app/argocd-mcp/token-registry.json

ファイルには、ベース URL とそれに使用するトークンを対応付ける JSON 配列を記述します。

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

ファイルを保護してください。 サーバーのユーザーだけがアクセスできるように制限し（例：chmod 400）、ディスク上のプレーンテキストファイルよりも、シークレット管理の仕組み（Kubernetes シークレットボリューム、Vault エージェントなど）を優先してください。

ローカル開発。 make run / make dev ターゲットは、デフォルトではレジストリなしで実行されます。レジストリを使用するには、ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json を渡してください。ファイルを dist/ の下に置かないでください。tsup は clean: true で実行され、ビルドのたびにこのディレクトリを消去します。ローカルでの実行を参照してください。

レジストリを設定すると、呼び出し元は（シークレットではない）argocdBaseUrl 引数のみを渡してインスタンスを指定でき、サーバーが登録済みのトークンと組み合わせます。トークンがツール呼び出しのペイロードに含まれることはありません。

2 種類のトークン

サーバーは、2 種類の異なるトークンのいずれかを使用して呼び出しを解決します。この違いを理解することが、セキュリティモデルを機能させるうえで重要です。

	デフォルトトークン	レジストリトークン
ソース	x-argocd-api-token ヘッダー / ARGOCD_API_TOKEN 環境変数（セッション認証情報）	baseUrl をキーとする ARGOCD_TOKEN_REGISTRY_PATH JSON ファイル内の token エントリ
スコープ	デフォルトのベース URL のみ（x-argocd-base-url / ARGOCD_BASE_URL）	エントリのキーに指定された特定のベース URL
使用対象	デフォルトのベース URL を対象とする呼び出し	レジストリに存在する任意のベース URL（フォールバックとしてデフォルトも含む）を対象とする呼び出し
使用しない対象	デフォルト以外のベース URL — 別のホストに送信されることはありません	登録されていないベース URL

最も重要なルールは、デフォルトトークンはデフォルトのベース URL に紐付けられ、それ以外のホストのトークンは必ずレジストリから取得することです。レジストリトークンは、登録先のホストにのみ紐付けられます。

解決順序

指定した呼び出しのベース URL は、argocdBaseUrl 引数が指定されていればその値、指定されていなければセッションのデフォルト値になります。続いて、トークンは次の順序で選択されます。

1. 呼び出し先がデフォルトのベース URL → デフォルトトークンを使用します。デフォルトトークンが指定されていない場合（トークンなしのセッション）は、そのベース URL のレジストリトークンがあれば、それを使用します。
2. 呼び出し先がその他のベース URL → そのベース URL のレジストリトークンのみを使用します。ここではデフォルトトークンは決して使用されません。デフォルト以外のホストには送信されません。
3. いずれにも該当しない場合（要求されたベース URL のトークンを解決できない場合）、呼び出しは「Missing required ArgoCD API token」エラーを返し、そのホストへのリクエストは送信されません。

デフォルトトークンをデフォルトのベース URL に紐付ける理由。 argocdBaseUrl 引数はツール呼び出しから渡されるため、呼び出し元（またはプロンプトインジェクションを受けたモデル）が任意のホストを指定する可能性があります。デフォルトトークンが指定された任意のベース URL と組み合わされると、そのトークンが Authorization: Bearer ヘッダーとして攻撃者のホストに送信されてしまいます。デフォルトトークンの使用先をデフォルトのベース URL に限定し、その他のホストには明示的なレジストリエントリを必須にすることで、このトークンの流出を防止します。追加のインスタンスを対象にするには、事前にそのトークン（ひいてはホスト名）を登録する必要があります。

ベース URL は参照時に正規化されます（ホスト名を小文字にし、末尾のスラッシュを無視します）。そのため、書式に多少の違いがあっても一致します。レジストリが設定されている場合、接続時に HTTP トランスポートが x-argocd-api-token を必須としなくなるため、呼び出しごとのベース URL からトークンを解決できます。ARGOCD_TOKEN_REGISTRY_PATH が設定されているのに、ファイルが存在しない、読み取れない、または形式が不正な場合、サーバーはフェイルクローズします。デフォルトの認証情報に黙ってフォールバックするのではなく、起動時に例外をスローするため、レジストリの設定ミスによって誤ったトークンで呼び出しがルーティングされることはありません。

たとえば、ベース URL のみを上書きする tools/call リクエストは次のとおりです。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_applications",
    "arguments": {
      "argocdBaseUrl": "https://argocd.other-cluster.example.com"
    }
  }
}

ベース URL を別のインスタンスに上書きするには、レジストリトークンが必要です。 デフォルトトークン（x-argocd-api-token / ARGOCD_API_TOKEN）はデフォルトのベース URL のみに紐付けられ、別のホストには送信されません。argocdBaseUrl をデフォルトのインスタンス（ホストが同じで、書式の違いを除く）に向けて上書きするとデフォルトトークンが再利用されますが、その他のインスタンスに向ける場合は、そのインスタンスのレジストリトークンが必要です。トークンがない場合、呼び出しは「Missing required ArgoCD API token」で失敗し、リクエストは送信されません。これは意図された動作です。上記のデフォルトトークンをデフォルトのベース URL に紐付ける理由を参照してください。

ネットワークへの公開

http および sse トランスポートは、create_application、delete_application、sync_application、run_resource_action を含むすべての ArgoCD ツールにアクセスできるネットワークリスナーを開きます。デフォルトでは、ループバックのみにバインドされます。

ARGOCD_API_TOKEN では保護されません。 このトークンは、このサーバーが ArgoCD に対して認証するためのものです。呼び出し元が誰であるかは示しません。受信アクセスは、以下の設定で制御します。

設定	フラグ	環境変数	デフォルト	動作
バインドアドレス	--bind-address	MCP_BIND_ADDRESS	127.0.0.1	リスナーが接続を受け付けるアドレスです。
受信トークン	—	MCP_AUTH_TOKEN	未設定	設定すると、すべてのリクエストに Authorization: Bearer <token> を含める必要があります。
許可する Host	--allowed-host-header	—	ループバック名	リクエストの Host ヘッダーで受け付ける追加のホスト名です。ホスト名ごとに繰り返し指定します。
許可する Origin	--allowed-origin	—	ループバックオリジン	リクエストの Origin ヘッダーで受け付ける追加のブラウザーオリジンです。オリジンごとに繰り返し指定します。
外部認証	--allow-unauthenticated	—	false	前段で呼び出し元を認証しているものがある場合に、トークンなしでループバック以外にバインドできるようにします。
ポート	--port	—	3000	リッスンするポートです。

--bind-address は、接続できる相手を決定します。--allowed-host-header は、接続済みのクライアントが申告する内容をチェックするだけです。この2つは一対の設定ではなく、後者はファイアウォールではありません。

環境変数のないフラグは、コンテナ内でも引数として渡します：docker run <image> http --allow-unauthenticated。

動作：

• バインド範囲を広げるには、MCP_AUTH_TOKEN または --allow-unauthenticated が必要です。どちらも指定しない場合、サーバーは理由をログに記録してゼロ以外の終了コードで終了し、公開状態で起動することはありません。
• Origin はスキーム、ホスト、ポートを常にチェックします。これにより、DNS リバインディングを利用するものも含め、悪意のある Web ページを防ぎます。
• Host はループバックにバインドしている場合、または少なくとも1つの --allowed-host-header が指定されている場合にチェックされます。それ以外の場合は、クライアントが正当に使用するホスト名が不明なため、チェックはスキップされ、警告がログに記録されます。
• GET /healthz はチェックの対象外のため、kubelet のプローブは引き続き成功します。返されるのは稼働状態のみです。
• 使用できない設定がある場合は無視せず、理由を示して起動時に失敗します。
• 読み取り専用モードはこれらとは独立しており、どの呼び出し元が実行できる操作も制限します。

リスナーを意図的に公開する場合：

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

コンテナイメージもループバックへのバインドをデフォルトとしているため、同じ Kubernetes ポッド内のサイドカーのように、呼び出し元がネットワーク名前空間を共有している場合は追加の設定は不要です。

docker run -e ARGOCD_BASE_URL=<argocd_url> -e ARGOCD_API_TOKEN=<argocd_token> \
  argoprojlabs/mcp-for-argocd

ポートを公開するには、バインド範囲を広げ、受信認証情報を設定します。

docker run -p 3000:3000 \
  -e ARGOCD_BASE_URL=<argocd_url> -e ARGOCD_API_TOKEN=<argocd_token> \
  -e MCP_BIND_ADDRESS=0.0.0.0 -e MCP_AUTH_TOKEN=<inbound_token> \
  argoprojlabs/mcp-for-argocd

バインド範囲を広げており、プロキシやメッシュがすでに呼び出し元を認証している場合は、MCP_AUTH_TOKEN の代わりに --allow-unauthenticated を使用します。

デプロイ時の注意事項については、運用者向けの注意事項を参照してください。

読み取り専用モード

リソースやアプリケーションの変更を避けるために、MCP Server を読み取り専用モードで実行する場合は、次の環境変数を設定してください。

"MCP_READ_ONLY": "true"

これにより、次のツールが無効になります。

• create_application
• update_application
• delete_application
• sync_application
• run_resource_action

デフォルトでは、すべてのツールを使用できます。

ステートレスモード

デフォルトでは、HTTP トランスポートは各クライアント接続にセッション ID を割り当て、アクティブなセッションのマップをメモリ内に保持します。単一インスタンスのデプロイでは問題なく動作しますが、スティッキーセッションを設定せずに複数のレプリカを実行すると、元のポッドで作成されたセッションが別のポッドにルーティングされたリクエストから見つからず、400 エラーが発生します。

セッションアフィニティの要件なしで実行するには、--stateless フラグを付けてサーバーを起動します。

node dist/index.js http --stateless

または、Docker を使用します。

docker run -p 3000:3000 \
  -e ARGOCD_BASE_URL=<argocd_url> -e ARGOCD_API_TOKEN=<argocd_token> \
  -e MCP_BIND_ADDRESS=0.0.0.0 -e MCP_AUTH_TOKEN=<inbound_token> \
  argoprojlabs/mcp-for-argocd http --stateless

イメージには ENTRYPOINT が設定されているため、コマンドを上書きしても置き換わるのは引数のみです。ポートを公開することで、より広い範囲へのバインドとインバウンドトークンが必要になります。詳しくはネットワーク公開をご覧ください。

ステートレスモードでは：

• Mcp-Session-Id は返されず、要求もされません。どのレプリカでも、あらゆるリクエストを処理できます
• ArgoCD の認証情報は、環境変数または x-argocd-base-url / x-argocd-api-token ヘッダーを介して、リクエストごとに指定する必要があります（ベース URL は argocdBaseUrl ツール引数で呼び出しごとに上書きすることもできます。API トークンはヘッダーまたは環境変数でのみ指定できます）
• GET /mcp と DELETE /mcp は 405 Method Not Allowed を返します（セッションレベルの SSE と終了処理はサポートされません）

このモードは、ネットワークレベルのスティッキーセッションを利用できない、Horizontal Pod Autoscaling（HPA）を使用した Kubernetes デプロイで推奨されます。

開発向け

1. リポジトリをクローンします：

git clone https://github.com/argoproj-labs/mcp-for-argocd.git
cd mcp-for-argocd

2. プロジェクトの依存関係をインストールします：

pnpm install

3. ホットリロードを有効にして開発サーバーを起動します：

pnpm run dev

サーバーの起動後、Visual Studio Code やその他の MCP クライアントで MCP サーバーを利用できます。

ローカルでの実行

Makefile には、HTTP トランスポートでサーバーを実行するためのターゲットが用意されています。

make run    # build, then run the HTTP server (production-style)
make dev    # run from source with hot reloading (tsx watch)

デフォルトでは、どちらのターゲットも認証情報を設定しません。サーバーはデフォルトのベース URL やトークンなしで起動するため、呼び出しごとに指定する必要があります（x-argocd-base-url／x-argocd-api-token ヘッダー、またはレジストリを設定した後の argocdBaseUrl ツール引数）。ポートも同じ方法で変更できます。

make run PORT=4000

認証情報を設定するには、コマンドラインで該当する環境変数をエクスポートします。環境変数は 3 つあり、すべて任意です。

変数	用途
ARGOCD_BASE_URL	呼び出しで上書きされない場合に使用する、デフォルトの ArgoCD インスタンス URL です。
ARGOCD_API_TOKEN	デフォルトのベース URL 用の静的 API トークンです。
ARGOCD_TOKEN_REGISTRY_PATH	ベース URL とトークンを対応付ける JSON トークンレジストリのパスです（複数のインスタンスを対象にする場合に使用します）。

これらはすべて送信先に対する認証情報です。リスナーへのアクセスを許可する対象については、ネットワークへの公開を参照してください。

# Single instance with a static base URL + token:
make run ARGOCD_BASE_URL=https://argo.example.com ARGOCD_API_TOKEN=<token>

# Multiple instances via a token registry:
make run ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json

# Both — a default instance plus extra instances resolved from the registry:
make dev ARGOCD_BASE_URL=https://argo.example.com ARGOCD_API_TOKEN=<token> \
  ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json

デフォルトのトークンとレジストリの連携方法については、トークンの解決を参照してください。ARGOCD_TOKEN_REGISTRY_PATH が設定されているのにファイルが見つからない、読み取れない、または形式が不正な場合、サーバーは起動時にフェイルクローズします。

トークンをシェルの履歴に残さないでください。 ARGOCD_API_TOKEN=<token> を make コマンドラインに直接渡すと、シークレットがシェルの履歴に記録され、プロセス一覧にも表示されます。make の呼び出しに含まれないよう、先にシェルでエクスポートしてください。

export ARGOCD_API_TOKEN=<token>
make run ARGOCD_BASE_URL=https://argo.example.com

レジストリのパス（ARGOCD_TOKEN_REGISTRY_PATH）とベース URL はシークレットではないため、コマンドラインに直接渡しても問題ありません。

レジストリファイルを dist/ の下に置かないでください。tsup は clean: true でビルドするため、ビルドのたびにそのディレクトリが消去されます。

HTTP サーバーは POST /mcp（デフォルトでは 127.0.0.1:3000。公開範囲を広げる方法についてはネットワークへの公開を参照）で待ち受け、稼働状態を確認するための GET /healthz エンドポイントも提供します。リクエストを送信するには、まずセッションを initialize して（レスポンスヘッダーの mcp-session-id を取得し）、登録済みのベース URL のいずれかを argocdBaseUrl 引数に指定してツールを呼び出します。

# 1. Initialize a session — note the mcp-session-id response header
curl -sD - http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

# 2. Call a tool, reusing that session id
curl -s http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'mcp-session-id: <session-id-from-step-1>' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_applications","arguments":{"argocdBaseUrl":"https://argo-a.example.com"}}}'

セッション ID の管理を避けるには、ステートレスモード（node dist/index.js http --stateless）で実行すると、各 POST /mcp が単独で処理されます。

ArgoCD の型定義の更新

最新の Argo CD API 仕様に基づいて TypeScript の型定義を更新するには、次の手順を実行します。

1. ArgoCD のリリースページから swagger.json ファイルをダウンロードします。たとえば、ArgoCD v2.14.11 の swagger.json のリンクはこちらです。

2. ダウンロードした swagger.json ファイルを argocd-mcp プロジェクトのルートディレクトリに配置します。

3. 次のコマンドを実行して、Swagger 定義から TypeScript の型を生成します。これにより、src/types/argocd.d.ts ファイルが作成または上書きされます。

   pnpm run generate-types
   

4. 新たに生成された src/types/argocd.d.ts から必要な型をエクスポートするように、src/types/argocd-types.ts ファイルを更新します。この手順では、必要な型だけが公開されるよう、手動で確認することがよくあります。

クレジット

このプロジェクトは、Akuity の @jiachengxu、@imwithye、@hwwn、@alexmt によって最初に作成され、寄贈されました。