ArgoCD MCP Server

ArgoCD MCP サーバー

ArgoCD API と連携する MCP（Model Context Protocol）サーバーです。AI アシスタントや LLM が、自然言語でのやり取りを通じて ArgoCD アプリケーションやリソースを管理できるようにします。

機能

• 認証とセッション管理：
  • ArgoCD API からのユーザー情報の取得
  • ArgoCD に対するトークンベースの認証
  • サーバー設定および構成へのアクセス
  • プラグイン情報の取得
  • バージョン情報の取得
• アプリケーション管理：
  • プロジェクト、名前、名前空間でのアプリケーションの一覧表示とフィルタリング
  • アプリケーションの詳細情報の取得
  • アプリケーションの作成、更新、削除
  • 設定可能なオプションを指定したアプリケーションの同期
• 堅牢な API クライアント：
  • URL の正規化とインテリジェントなエンドポイント処理
  • 包括的なエラー処理と詳細なエラーメッセージ
  • タイムアウトと SSL 検証の設定
  • トークンのセキュリティ保護とマスキング
• 開発者エクスペリエンス：
  • mypy による完全な静的型チェック
  • 詳細なドキュメントと例
  • 環境変数ベースの構成

クイックスタート

セットアップ

# Clone the repository
git clone https://github.com/severity1/argocd-mcp.git
cd argocd-mcp

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install dependencies
uv pip install -e .

サーバーの起動

サーバーは環境変数で設定します。設定可能な項目は次のとおりです。

環境変数	説明	デフォルト値
ARGOCD_TOKEN	ArgoCD API トークン	None
ARGOCD_API_URL	ArgoCD API エンドポイント	https://argocd.example.com/api/v1
ARGOCD_VERIFY_SSL	SSL 証明書を検証するかどうか	true

サーバーは次のいずれかの方法で起動できます。

# Using MCP dev tools (provides debugging tools)
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
mcp dev server.py

# Using MCP run command
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
mcp run server.py

# Standard method
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
uv run server.py

# Setting multiple environment variables
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
export ARGOCD_API_URL=https://your-argocd-server.com:9000/api/v1
export ARGOCD_VERIFY_SSL=false  # Disable SSL verification for self-signed certs
uv run server.py

# Using a .env file
echo "ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
ARGOCD_API_URL=https://your-argocd-server.com:9000/api/v1
ARGOCD_VERIFY_SSL=false" > .env
uv run server.py

# Run in background
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
uv run server.py > server.log 2>&1 & echo $! > server.pid

トークンを環境変数で指定すると、Claude はコマンドごとにトークンを指定しなくても使用できます。

Claude との接続

Claude Code CLI を使用する

# Add the MCP server
claude mcp add argocd-mcp "uv run $(pwd)/server.py"

# With token
claude mcp add argocd-mcp -e ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN -- "uv run $(pwd)/server.py"

# Verify it was added
claude mcp list

# For debugging, you can use MCP Inspector with 'mcp dev' command

Claude Desktop を使用する

claude_desktop_config.json 構成ファイルを作成します。

{
  "mcpServers": {
    "argocd-mcp": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/path/to/argocd-mcp",
        "run",
        "server.py"
      ],
      "env": {
        "ARGOCD_TOKEN": "your_argocd_token",
        "ARGOCD_API_URL": "https://your-argocd-server.com/api/v1",
        "ARGOCD_VERIFY_SSL": "true"
      }
    }
  }
}

パスと構成値を実際の値に置き換えてください。

• uv 実行ファイルのフルパスを指定します（macOS/Linux では which uv、Windows では where uv で確認できます）。
• argocd-mcp のインストール先ディレクトリの正しいパスを設定します。
• ArgoCD API トークンを追加します。
• 必要に応じて、その他の環境変数を設定します。

この構成により、指定した環境設定を使用して MCP サーバーを自動的に起動する方法が Claude Desktop に伝えられます。

利用可能なツール

セッションツール

• get_user_info：api/v1/session/userinfo 経由で現在のユーザー情報を取得します。

設定ツール

• get_settings：UI、OIDC、その他の設定を含む ArgoCD サーバー設定を取得します。
• get_plugins：設定済みの ArgoCD プラグインに関する情報を取得します。

バージョンツール

• get_version：API サーバーのバージョン情報を取得します。

アプリケーション管理ツール

• list_applications：フィルタリングオプションを指定して、すべてのアプリケーションを取得します。
• get_application_details：特定のアプリケーションの詳細情報を取得します。
• create_application：新しいアプリケーションを作成します。
• update_application：既存のアプリケーションを更新します。
• delete_application：アプリケーションを削除します。
• sync_application：アプリケーションの同期処理を開始します。

会話例

ユーザー情報の確認

User: What's my user information in ArgoCD?

Claude: Let me retrieve your user information.

⏺ argocd-mcp:get_user_info (MCP)
  ⎿  {"loggedIn": true, "username": "devops-user", "iss": "argocd"}

You are logged in as 'devops-user'.

ArgoCD のバージョンの取得

User: What version of ArgoCD is running on the server?

Claude: Let me check the ArgoCD version information.

⏺ argocd-mcp:get_version (MCP)
  ⎿  {
        "Version": "v2.9.3+5eaf684",
        "BuildDate": "2023-09-15T14:25:11Z",
        "GitCommit": "5eaf68452",
        "GitTreeState": "clean",
        "GoVersion": "go1.20.7",
        "Compiler": "gc",
        "Platform": "linux/amd64",
        "KustomizeVersion": "v5.1.1",
        "HelmVersion": "v3.12.3",
        "KubectlVersion": "v1.27.4",
        "JsonnetVersion": "v0.20.0"
      }

You're running ArgoCD v2.9.3, built on September 15, 2023. It's running on Linux (amd64) with Go 1.20.7, and includes Kustomize v5.1.1 and Helm v3.12.3.

ArgoCD 設定の取得

User: Show me the ArgoCD server settings

Claude: Let me retrieve the ArgoCD server settings for you.

⏺ argocd-mcp:get_settings (MCP)
  ⎿  {
        "clusterSettings": {
          "appLabelKey": "argocd.argoproj.io/instance",
          "controllerNamespace": "argocd",
          "execEnabled": true,
          "statusBadgeEnabled": true,
          "uiBannerContent": "This is a development instance of ArgoCD",
          "url": "https://argocd.example.com"
        }
      }

Here are the key settings for your ArgoCD server:
- URL: https://argocd.example.com
- Controller namespace: argocd
- Exec enabled: Yes
- Status badge enabled: Yes
- UI Banner: "This is a development instance of ArgoCD"

アプリケーションの管理

User: What applications do I have in the "production" project?

Claude: Let me list your applications in the production project.

⏺ argocd-mcp:list_applications (MCP)
  ⎿  {
        "items": [
          {
            "metadata": {
              "name": "frontend-app",
            },
            "status": {
              "sync": {"status": "Synced"},
              "health": {"status": "Healthy"},
            }
          },
          {
            "metadata": {
              "name": "api-service",
            },
            "status": {
              "sync": {"status": "OutOfSync"},
              "health": {"status": "Healthy"},
            }
          },
          {
            "metadata": {
              "name": "database",
            },
            "status": {
              "sync": {"status": "Synced"},
              "health": {"status": "Degraded"},
            }
          }
        ]
      }

You have 3 applications in the production project:
- frontend-app (Synced, Healthy)
- api-service (OutOfSync, Healthy)
- database (Synced, Degraded)

User: Sync the api-service application

Claude: I'll sync the api-service application for you.

⏺ argocd-mcp:sync_application (MCP)
  ⎿  {
        "resourcesResult": {
          "updated": ["Deployment/api-service"],
          "hooks": []
        },
        "status": "Syncing"
      }

Application sync initiated successfully. The sync operation is now in progress.

開発

要件

• Python 3.12+
• MCP（FastMCP と開発ツールを含む）
• uv パッケージマネージャー（推奨）または pip
• ArgoCD API トークン

型チェック

このプロジェクトでは、コード品質を高め、型関連のバグを早期に検出するために、静的型チェックに mypy を使用しています：

# Install mypy
uv pip install mypy

# Run type checking
uv run -m mypy .

型チェックの設定は pyproject.toml と mypy.ini の両方で確認できます。この設定では、次のような厳格な型付けルールが適用されます：

• 型注釈のない定義を禁止
• Any 型の返却時に警告
• 関数定義の完全性をチェック
• 名前空間パッケージをサポート
• モジュール固有の設定

プロジェクト構成

コードはモジュール化された構成で整理されています：

argocd-mcp/
├── api/              # API client and communication
│   ├── __init__.py
│   └── client.py     # HTTP client for ArgoCD API
├── models/           # Data models
│   ├── __init__.py
│   └── applications.py # Application data structures
├── tools/            # MCP tools implementation
│   ├── __init__.py
│   ├── session.py    # Session tools (user info)
│   ├── applications.py # Application management tools
│   ├── settings.py   # Server settings tools
│   └── version.py    # Version information tools
├── utils/            # Utility functions
│   ├── __init__.py
├── server.py         # Main server entry point
├── pyproject.toml    # Project configuration and dependencies
└── mypy.ini          # Mypy type checking configuration

サーバーの拡張

新しい機能を追加するには：

1. tools ディレクトリ内の適切なモジュールに新しいツールを追加します
2. server.py に新しいツールを登録します
3. パラメーターの検証とエラー処理には、既存のパターンに従います
4. README.md のドキュメントを更新します
5. 新しい機能のテストを追加します

トラブルシューティング

問題が発生した場合：

1. サーバーログを確認します（デフォルトで情報ログが有効です）
2. Processing request of type CallToolRequest は情報メッセージであり、エラーではないことに注意してください
3. mcp dev server.py を使用している場合、デバッグ用に MCP Inspector が http://localhost:5173 で自動的に開きます
4. サーバーログを使用して、API 呼び出しと応答をデバッグします
5. 自己署名証明書による SSL 証明書の問題が発生した場合：

# Disable SSL verification
export ARGOCD_VERIFY_SSL=false
uv run server.py

6. 必要な環境変数がすべて適切に設定されているか確認します：

# Show all current ArgoCD environment variables
env | grep ARGOCD

コントリビューション

コントリビューションを歓迎します！このプロジェクトに貢献したい場合は、イシューまたはプルリクエストを作成してください。

コントリビューションの際は、次のガイドラインに従ってください：

• すべてのコードに適切な型ヒントを含めます
• PR を提出する前に mypy による型チェックを実行します
• 新しい機能のテストを追加します
• 新機能や変更点についてドキュメントを更新します