ArgoCD MCP 서버
ArgoCD API와 통합되는 MCP(Model Context Protocol) 서버로, AI 어시스턴트와 대규모 언어 모델이 자연어 상호작용을 통해 ArgoCD 애플리케이션과 리소스를 관리할 수 있도록 합니다.
특징
- 인증 및 세션 관리 :
- ArgoCD API에서 사용자 정보 검색
- ArgoCD를 사용한 토큰 기반 인증
- 서버 설정 및 구성 액세스
- 플러그인 정보 검색
- 버전 정보 검색
- 애플리케이션 관리 :
- 프로젝트, 이름, 네임스페이스별로 애플리케이션을 나열하고 필터링합니다.
- 자세한 신청 정보를 받아보세요
- 애플리케이션 생성, 업데이트 및 삭제
- 구성 가능한 옵션으로 애플리케이션 동기화
- 강력한 API 클라이언트 :
- URL 정규화 및 지능형 엔드포인트 처리
- 포괄적인 오류 처리 및 자세한 오류 메시지
- 구성 가능한 시간 초과 및 SSL 검증
- 토큰 보안 보호 및 마스킹
- 개발자 경험 :
- MyPy를 사용한 전체 정적 유형 검사
- 자세한 문서 및 예제
- 환경 기반 구성
빠른 시작
설정
지엑스피1
서버 시작
서버는 환경 변수를 통해 구성됩니다. 사용 가능한 구성 옵션은 다음과 같습니다.
다음과 같은 여러 가지 방법으로 서버를 시작할 수 있습니다.
# 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 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 토큰을 추가하세요
- 필요에 따라 다른 환경 변수를 구성하세요
이 구성은 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.
개발
요구 사항
- 파이썬 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 모두에서 사용할 수 있습니다. 이 설정은 다음을 포함한 엄격한 타입 규칙을 적용합니다.
- 유형이 지정되지 않은 정의 허용 안 함
- 모든 유형을 반환할 때 경고
- 함수 정의의 완전성 확인
- 네임스페이스 패키지 지원
- 모듈별 구성
프로젝트 구조
코드는 모듈형 구조로 구성됩니다.
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 Inspector가 디버깅을 위해 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 유형 검사를 실행하세요.
- 새로운 기능에 대한 테스트 추가
- 새로운 기능이나 변경 사항에 대한 문서를 업데이트합니다.