/ 디렉터리 / 플레이그라운드 / ArgoCD
← 모든 서버 ↗ GitHub
● 공식 argoproj-labs 🔑 본인 키 필요

ArgoCD

제작: argoproj-labs · argoproj-labs/mcp-for-argocd

Claude에서 ArgoCD 애플리케이션을 검사, diff, 동기화 — kubectl 컨텍스트 전환 없이 GitOps 클러스터 상태 관리

ArgoProj Labs의 MCP는 ArgoCD API를 래핑합니다: 애플리케이션 목록 조회, 동기화/상태 확인, 원하는 상태와 실제 상태 비교, 동기화 트리거, 애플리케이션 매니페스트 읽기. 토큰 범위는 관찰 목적으로 읽기 전용이며, 동기화 또는 재정의가 필요할 때만 쓰기 권한을 사용합니다.

▶ 데모 보기 📦 설치 💡 사용 사례

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

argocd.replay ▶ 준비됨
0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "argocd",
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json
{
  "context_servers": {
    "argocd": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-for-argocd"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add argocd -- uvx mcp-for-argocd

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: ArgoCD

동기화에서 벗어난 ArgoCD 앱 찾기

👤 GitOps를 운영하는 플랫폼/SRE 팀 ⏱ ~20 min intermediate

언제 쓸까: 매주: 어떤 클러스터의 어떤 앱이 OutOfSync 또는 Degraded 상태인가, 그 이유는?

사전 조건
  • 읽기 범위의 ArgoCD API 토큰 — argocd account generate-token --account <read-only-user>
  • ArgoCD 서버 URL — ARGOCD_SERVER=argocd.my.company.com
흐름
  1. 상태를 포함한 앱 목록 조회
    모든 ArgoCD 앱을 나열합니다. 각각: 이름, 프로젝트, 동기화 상태, 상태, 마지막 동기화 시간.✓ 복사됨
    → 전체 인벤토리
  2. 동기화 편차에 집중
    syncStatus != 'Synced' 또는 health != 'Healthy'인 앱으로 필터링합니다. 마지막 동기화 이후 시간으로 순위를 매깁니다.✓ 복사됨
    → 문제 앱 목록
  3. 특정 앱 비교
    앱 <name>의 원하는 상태(git)와 실제 상태 간의 diff를 표시합니다. 어떤 리소스가 동기화되지 않았는가?✓ 복사됨
    → 리소스 수준 diff

결과: 주간 편차 보고서로 어떤 앱이 주의가 필요하고 그 이유를 식별합니다.

함정
  • 합법적인 런타임 전용 리소스로 인한 편차(예: HPA 스케일된 레플리카) — 런타임에 변경되는 필드를 제외하도록 Application spec에서 ignoreDifferences를 구성하십시오.
함께 쓰기: notion

특정 애플리케이션에 대한 동기화 검토 및 적용

👤 변경 사항을 배포하는 DevOps 엔지니어 ⏱ ~15 min intermediate

언제 쓸까: PR이 main에 병합됨; ArgoCD가 앱을 OutOfSync로 표시하고 승인 대기 중

사전 조건
  • 대상 프로젝트에서 동기화 권한이 있는 토큰 — applications, sync, <project>/* 권한이 있는 역할
흐름
  1. 보류 중인 변경 사항 검사
    앱 <name>의 diff를 표시합니다. 어떤 리소스가 변경되고, 영향 범위는 어디까지인가?✓ 복사됨
    → 구체적인 diff
  2. 소스 커밋 확인
    원하는 상태가 가리키는 커밋 SHA는 무엇인가? GitHub 커밋 메시지와 PR을 표시합니다.✓ 복사됨
    → 커밋 + PR 컨텍스트
  3. 먼저 prune=false로 동기화
    <name>에 대해 prune=false, dryRun=false로 동기화를 트리거합니다. 완료 대기, 최종 상태를 표시합니다.✓ 복사됨
    → Sync Succeeded; health Healthy

결과: 사전 검토를 통한 배포이며 예상 외 상황이 없습니다; prune에 의한 삭제는 명시적으로만 발생합니다.

함정
  • prune=true를 사용한 동기화는 여전히 필요한 리소스를 삭제할 수 있습니다. — 항상 prune=false로 시작하십시오; 네임스페이스에 수동으로 생성된 리소스가 없음을 확인한 후에만 prune을 활성화하십시오.
함께 쓰기: github

이전 Git 리비전으로의 긴급 롤백

👤 배포 오류 사건 중의 SRE ⏱ ~15 min advanced

언제 쓸까: 배포가 진행되었고 오류가 급증했으며, 마지막으로 알려진 양호한 버전으로 롤백해야 합니다.

흐름
  1. 현재 상태 및 기록 확인
    앱 <name>의 현재 리비전과 마지막 5개 배포된 리비전을 타임스탬프와 함께 표시합니다.✓ 복사됨
    → 기록 테이블
  2. 롤백 대상 선택
    2개 동기화 전 리비전은 무엇이었나요? 해당 SHA가 사건 시작 전의 Git 커밋과 일치하는지 확인합니다.✓ 복사됨
    → 대상 SHA 식별됨
  3. 롤백
    <name>을 리비전 <SHA>로 동기화하되 prune=false로 설정합니다. Healthy가 될 때까지 모니터링하십시오. 완료되면 Teams에 게시합니다.✓ 복사됨
    → 앱 되돌림 + 알림 전송됨

결과: 감사 추적을 포함한 깔끔한 롤백, 일반적으로 5분 이내입니다.

함정
  • 앱만 롤백하지만 DB 마이그레이션은 이미 진행됨 — DB 마이그레이션에는 자체 롤백 계획이 필요합니다; 때로는 변경된 스키마에 대해 코드를 롤백하는 것보다 수정을 포함한 '롤 포워드'가 더 안전합니다.
함께 쓰기: sentry · ms-teams

클러스터 간 앱 인벤토리 구축

👤 많은 클러스터를 관리하는 플랫폼 팀 ⏱ ~20 min intermediate

언제 쓸까: ArgoCD를 hub-spoke 모델로 운영하고 평탄한 목록을 원할 때: '어떤 앱이 어디서 실행되는가'

흐름
  1. ArgoCD가 관리하는 클러스터 목록
    ArgoCD에 등록된 모든 클러스터를 이름과 서버 URL과 함께 나열합니다.✓ 복사됨
    → 클러스터 인벤토리
  2. 앱을 클러스터로 매핑
    각 앱에 대해 대상 클러스터 및 네임스페이스를 표시합니다. 클러스터별로 그룹화합니다.✓ 복사됨
    → 클러스터별 앱 목록
  3. 비정상적인 배치 플래그
    'prod-only' 앱이 dev 클러스터에 배포된 것과 같이 예상치 못한 클러스터에 배포된 앱이 있는가? 이유와 함께 플래그 지정합니다.✓ 복사됨
    → 이상 목록

결과: 무엇이 어디서 실행되는지에 대한 최신 맵, 감사 및 용량 계획에 유용합니다.

함정
  • 만료된 클러스터 항목 — 시크릿이 제거되었지만 클러스터는 여전히 나열됨 — 주기적으로 각 클러스터에 액세스할 수 있는지 확인; 만료된 항목을 제거합니다.

조합

다른 MCP와 조합해 10배 효율

argocd + github

Argo 동기화와 이를 유발한 PR 상호 참조

앱 <name>의 현재 리비전 SHA를 표시합니다; 이를 도입한 GitHub PR을 가져와서 변경 사항을 요약합니다.✓ 복사됨
argocd + sentry

Argo 동기화와 배포 후 오류 급증 연관짓기

앱 <name>이 14:02에 동기화됨; Sentry 오류가 그 이후로 급증했는가? 맞다면, 도입된 상위 문제를 표시합니다.✓ 복사됨
argocd + ms-teams

Teams 채널에 동기화/롤백 이벤트 게시

앱 <name>을 수동으로 동기화한 후, Teams #deploys 채널에 리비전 SHA와 누가 트리거했는지를 포함한 메시지를 게시합니다.✓ 복사됨

도구

이 MCP가 노출하는 것

도구입력언제 호출비용
list_applications project?, selector? 앱 인벤토리 무료
get_application name 특정 앱의 상세 상태 무료
get_application_diff name, revision? 동기화가 변경할 내용 미리보기 무료
sync_application name, revision?, prune?, dryRun?, resources? 보류 중인 변경 사항 적용 무료 (클러스터 작업 트리거)
get_application_resource_tree name 앱이 소유한 실제 리소스 검사 무료
list_clusters 클러스터 간 인벤토리 무료

비용 및 제한

운영 비용

API 쿼터
ArgoCD 서버 용량으로 제한됨; 실질적 한계 ~10 req/s
호출당 토큰
앱 목록: 500–3000 토큰. Diff: 최대 5000.
금액
무료 — ArgoCD는 오픈 소스이며, 인프라 호스팅 비용만 지불합니다.
팁
앱 목록을 캐싱합니다; 모든 것을 나열하는 대신 선택자(프로젝트, 레이블)를 사용하여 쿼리를 좁혀줍니다.

보안

권한, 시크릿, 파급범위

최소 스코프: 읽기 전용 세션을 위한 applications, clusters에 대한 읽기 권한
자격 증명 저장: 환경의 ARGOCD_AUTH_TOKEN 및 ARGOCD_SERVER
데이터 외부 송신: ArgoCD 서버로의 호출만
절대 부여 금지: admin 모든 프로젝트에서 이유 없이 동기화 account:update

문제 해결

자주 발생하는 오류와 해결

401 인증되지 않음

ARGOCD_AUTH_TOKEN이 만료되거나 취소됨. argocd account generate-token을 통해 재생성하십시오.

확인: argocd account get-user-info --auth-token $ARGOCD_AUTH_TOKEN
403 동기화에 대한 권한 거부됨

역할에 applications, sync, <project>/* 권한이 없습니다. AppProject 또는 계정 역할을 업데이트하십시오.

Sync가 10분 이상 Progressing 상태로 멈춤

일반적으로 멈춘 리소스 — resource-tree에서 실패한 훅 또는 멈춘 컨트롤러를 확인합니다; 클러스터 내 수동 개입이 필요할 수 있습니다.

Diff가 매 동기화마다 예상치 못한 편차 표시

컨트롤러가 런타임에 필드를 변경함. Application spec에 해당 필드에 대한 ignoreDifferences를 추가하십시오.

대안

ArgoCD 다른 것과 비교

대안언제 쓰나단점/장점
Flux MCPGitOps를 위해 ArgoCD 대신 Flux를 사용하는 경우다른 GitOps 엔진; CLI 중심 모델
Kubernetes MCP (raw kubectl)GitOps 추상화 없이 클러스터에 직접 액세스하려는 경우명령형 — 관리되는 앱에 대한 GitOps의 목적을 무산시킴

더 보기

리소스

📖 GitHub에서 공식 README 읽기

🐙 열린 이슈 보기

🔍 400+ MCP 서버 및 Skills 전체 보기