ArgoCD MCP サーバー
ArgoCD API と統合された MCP (モデル コンテキスト プロトコル) サーバー。AI アシスタントと大規模言語モデルが自然言語の対話を通じて ArgoCD アプリケーションとリソースを管理できるようになります。
特徴
- 認証とセッション管理:
- ArgoCD APIからのユーザー情報取得
- ArgoCD によるトークンベースの認証
- サーバー設定と構成へのアクセス
- プラグイン情報の取得
- バージョン情報の取得
- アプリケーション管理:
- プロジェクト、名前、名前空間でアプリケーションを一覧表示およびフィルタリングします
- 詳細な申請情報を入手する
- アプリケーションの作成、更新、削除
- 設定可能なオプションでアプリケーションを同期する
- 堅牢なAPIクライアント:
- URLの正規化とインテリジェントなエンドポイント処理
- 包括的なエラー処理と詳細なエラーメッセージ
- 設定可能なタイムアウトとSSL検証
- トークンのセキュリティ保護とマスキング
- 開発者エクスペリエンス:
- mypy による完全な静的型チェック
- 詳細なドキュメントと例
- 環境ベースの構成
クイックスタート
設定
# Clone the repository
git clone https://github.com/yourusername/argocd-mcp.git
cd argocd-mcp
# Create virtual environment and activate it
uv venv
source .venv/bin/activate
# Install dependencies
uv pip install -e .
サーバーの起動
サーバーは環境変数を介して設定されます。利用可能な設定オプションは次のとおりです。
サーバーはいくつかの方法で起動できます。
# 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 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デスクトップの使用
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トークンを追加する
- 必要に応じて他の環境変数を設定します
この構成は、Claude Desktop に、特定の環境設定で MCP サーバーを自動的に起動する方法を指示します。
利用可能なツール
セッションツール
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
サーバーの拡張
新しい機能を追加するには:
toolsディレクトリ内の適切なモジュールに新しいツールを追加しますserver.pyに新しいツールを登録する- パラメータ検証とエラー処理の既存のパターンに従う
- README.md のドキュメントを更新します
- 新しい機能のテストを追加する
トラブルシューティング
問題が発生した場合:
- サーバーログを確認します（情報ログはデフォルトで有効になっています）
Processing request of type CallToolRequestエラーではなく情報であることに注意してくださいmcp dev server.pyを使用する場合、デバッグのために MCP インスペクタがhttp://localhost:5173で自動的に開きます。- サーバーログを使用してAPI呼び出しと応答をデバッグする
- 自己署名証明書の SSL 証明書の問題の場合:
# Disable SSL verification
export ARGOCD_VERIFY_SSL=false
uv run server.py
- 必要な環境変数がすべて適切に設定されているかどうかを確認します。
# Show all current ArgoCD environment variables
env | grep ARGOCD
貢献
貢献を歓迎します！このプロジェクトに貢献したい場合は、問題を開くか、プルリクエストを送信してください。
貢献する際は、以下のガイドラインに従ってください。
- すべてのコードに適切な型ヒントが含まれていることを確認する
- PR を送信する前に mypy の型チェックを実行する
- 新しい機能のテストを追加する
- 新しい機能や変更があった場合はドキュメントを更新します