Argo CD MCP 서버

Argo CD를 위한 Model Context Protocol (MCP) 서버 구현으로, AI 어시스턴트가 자연어를 통해 Argo CD 애플리케이션과 상호작용할 수 있게 합니다. 이 서버는 stdio 및 HTTP 스트림 전송 프로토콜을 통해 Visual Studio Code 및 기타 MCP 클라이언트와 원활하게 통합됩니다.

argocd-mcp-demo

기능

전송 프로토콜: 다양한 클라이언트와의 유연한 통합을 위해 stdio 및 HTTP 스트림 전송 모드를 모두 지원합니다.
완벽한 Argo CD API 통합: Argo CD 리소스 및 작업에 대한 포괄적인 액세스를 제공합니다.
AI 어시스턴트 준비 완료: AI 어시스턴트가 자연어로 Argo CD와 상호작용할 수 있도록 사전 구성된 도구입니다.

사용 가능한 도구

이 서버는 다음과 같은 ArgoCD 관리 도구를 제공합니다:

클러스터 관리

list_clusters: ArgoCD에 등록된 모든 클러스터 나열

애플리케이션 관리

list_applications: 모든 애플리케이션 나열 및 필터링
get_application: 특정 애플리케이션에 대한 상세 정보 가져오기
create_application: 새 애플리케이션 생성
update_application: 기존 애플리케이션 업데이트
delete_application: 애플리케이션 삭제
sync_application: 애플리케이션에 대한 동기화 작업 트리거

리소스 관리

get_application_resource_tree: 특정 애플리케이션의 리소스 트리 가져오기
get_application_managed_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와 함께 사용

Cursor의 MCP 지원 문서를 따라 프로젝트에 .cursor/mcp.json 파일을 생성합니다:

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

Agent 모드에서 대화를 시작하여 MCP를 사용합니다.

VSCode와 함께 사용

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>"
      }
    }
  }
}

MCP를 지원하는 VS Code의 AI 어시스턴트와 대화를 시작합니다.

Claude Desktop과 함께 사용

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>"
      }
    }
  }
}

설정에서 이 구성 파일을 사용하도록 Claude Desktop을 구성합니다.

자체 서명 인증서

Argo CD 인스턴스가 자체 서명 인증서 또는 사설 인증 기관(CA)의 인증서를 사용하는 경우, 구성에 다음 환경 변수를 추가해야 할 수 있습니다:

"NODE_TLS_REJECT_UNAUTHORIZED": "0"

이는 자체 서명 인증서나 시스템 인증서 저장소에서 신뢰하지 않는 사설 CA의 인증서를 사용하는 Argo CD 인스턴스에 연결할 때 Node.js의 TLS 인증서 유효성 검사를 비활성화합니다.

경고: SSL 검증을 비활성화하면 보안이 저하됩니다. 이 설정은 개발 환경에서만 사용하거나 보안 영향을 이해하고 있는 경우에만 사용하십시오.

읽기 전용 모드

리소스나 애플리케이션 수정을 방지하기 위해 MCP 서버를 읽기 전용(ReadOnly) 모드로 실행하려면 다음 환경 변수를 설정해야 합니다:

"MCP_READ_ONLY": "true"

이렇게 하면 다음 도구가 비활성화됩니다:

create_application
update_application
delete_application
sync_application
run_resource_action

기본적으로 모든 도구를 사용할 수 있습니다.

상태 비저장(Stateless) 모드

기본적으로 HTTP 전송은 각 클라이언트 연결에 세션 ID를 할당하고 활성 세션의 메모리 내 맵을 유지합니다. 이는 단일 인스턴스 배포에서는 잘 작동하지만, 고정 세션(sticky sessions) 없이 여러 복제본이 실행되는 경우 400 오류를 발생시킵니다. 다른 파드로 라우팅된 요청은 원래 파드에서 생성된 세션을 찾을 수 없기 때문입니다.

세션 선호도 요구 사항 없이 실행하려면 --stateless 플래그를 사용하여 서버를 시작하십시오:

node dist/index.js http --stateless

또는 Docker를 사용하는 경우:

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

상태 비저장 모드에서는:

Mcp-Session-Id가 반환되거나 필요하지 않음 — 모든 복제본이 모든 요청을 처리할 수 있음
ArgoCD 자격 증명은 환경 변수 또는 x-argocd-base-url / x-argocd-api-token 헤더를 통해 모든 요청 시 제공되어야 함
GET /mcp 및 DELETE /mcp는 405 Method Not Allowed를 반환함 (세션 수준 SSE 및 종료는 지원되지 않음)

이 모드는 네트워크 수준의 고정 세션을 사용할 수 없는 HPA(Horizontal Pod Autoscaling)가 있는 Kubernetes 배포에 권장됩니다.

개발을 위한 정보

저장소 복제:

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

프로젝트 종속성 설치:

pnpm install

핫 리로딩이 활성화된 개발 서버 시작:

pnpm run dev

서버가 실행되면 Visual Studio Code 또는 다른 MCP 클라이언트 내에서 MCP 서버를 활용할 수 있습니다.

ArgoCD 타입 업그레이드

최신 Argo CD API 사양을 기반으로 TypeScript 타입 정의를 업데이트하려면:

ArgoCD 릴리스 페이지에서 swagger.json 파일을 다운로드합니다. 예를 들어, ArgoCD v2.14.11의 swagger.json 링크는 다음과 같습니다.
다운로드한 swagger.json 파일을 argocd-mcp 프로젝트의 루트 디렉토리에 배치합니다.
다음 명령을 실행하여 Swagger 정의에서 TypeScript 타입을 생성합니다. 이 작업은 src/types/argocd.d.ts 파일을 생성하거나 덮어씁니다:
```
pnpm run generate-types
```
src/types/argocd-types.ts 파일을 업데이트하여 새로 생성된 src/types/argocd.d.ts에서 필요한 타입을 내보냅니다. 이 단계는 필요한 타입만 노출되도록 수동 검토가 필요한 경우가 많습니다.

크레딧

이 프로젝트는 Akuity의 @jiachengxu, @imwithye, @hwwn, @alexmt에 의해 처음 생성되고 기증되었습니다.

Argo CD MCP Server