argoproj-labs/mcp-for-argocd

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

전송 프로토콜 (Transport Protocols): 다양한 클라이언트와의 유연한 통합을 위해 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
: 애플리케이션에 대한 동기화 (sync) 작업을 트리거합니다.

get_application_resource_tree
: 특정 애플리케이션의 리소스 트리 (resource tree)를 가져옵니다.

get_application_managed_resources
: 특정 애플리케이션이 관리하는 리소스를 가져옵니다.

get_application_workload_logs
: 애플리케이션 워크로드 (Pods, Deployments 등)의 로그를 가져옵니다.

get_resource_events
: 애플리케이션에 의해 관리되는 리소스의 이벤트를 가져옵니다.

get_resource_actions
: 리소스에 대해 사용 가능한 작업 (actions)을 가져옵니다.

run_resource_action
: 리소스에 대한 작업을 실행합니다.

• Node.js (v18 이상 권장)

• pnpm 패키지 매니저 (개발용)

• API 액세스가 가능한 Argo CD 인스턴스

• Argo CD API 토큰 (지침은 문서를 참조하세요)

• MCP 지원을 위해 Cursor 문서를 따르고, 프로젝트에 .cursor/mcp.json 파일을 생성하세요:

{
"mcpServers": {
"argocd-mcp": {
...

• MCP를 사용하려면 Agent 모드로 대화를 시작하세요.

• VS Code에서 MCP 서버를 사용하는(Use MCP servers in VS Code) 문서를 따르고, 프로젝트에 .vscode/mcp.json 파일을 생성하세요:

{
"servers": {
"argocd-mcp-stdio": {
...

• MCP를 지원하는 VS Code 내 AI 어시스턴트와 대화를 시작하세요.

• Claude Desktop에서 MCP를 사용하는(MCP in Claude Desktop) 문서를 따르고, claude_desktop_config.json 설정 파일을 생성하세요:

{
"mcpServers": {
"argocd-mcp": {
...

• 설정에서 이 설정 파일을 사용하도록 Claude Desktop을 구성하세요.

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

"NODE_TLS_REJECT_UNAUTHORIZED": "0"

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

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

서버는 **기본 URL (base URL)**과 **API 토큰 (API token)**을 사용하여 ArgoCD에 연결합니다.

ArgoCD API 토큰은 비밀 정보이며 오직 전송 계층 (transport layer)에서만 읽힙니다. 도구 호출 인자 (tool-call argument)로는 절대 읽히지 않습니다:

HTTP 헤더 (HTTP headers) (HTTP 전송 시에만 해당): x-argocd-api-token

.환경 변수 (Environment variables): ARGOCD_API_TOKEN (모든 전송 방식).

이것은 **기본 토큰 (default token)**입니다. 토큰 레지스트리 (token registry)가 구성되지 않은 경우 이는 필수 사항입니다: HTTP 전송 시, 토큰을 제공하지 않는 연결(헤더나 환경 변수 모두 없음)은 400 Bad Request로 거부되지만, 레지스트리가 구성된 경우 각 호출이 자체 레지스트리 토큰을 해결(resolve)하므로 토큰 없는 연결이 허용됩니다. 토큰을 도구 인자에서 제외함으로써 토큰이 프롬프트, 모델 컨텍스트 또는 도구 호출 로그에 절대 포함되지 않도록 보장합니다.

기본 URL은 세션 수준에서 제공될 수 있습니다 (서버가 시작될 때 또는 HTTP 클라이언트가 연결될 때 한 번 해결됨):

HTTP 헤더 (HTTP transport 전용): x-argocd-base-url

.환경 변수 (Environment variables): ARGOCD_BASE_URL

(모든 transport 적용).

또한, 모든 도구(tool)는 선택 사항인 argocdBaseUrl 인자를 허용합니다:

• 세션 기본 URL(session default base URL)이 존재하는 경우, argocdBaseUrl은 **선택 사항 (optional)**이며 해당 단일 호출에 대해 기본값을 덮어씁니다.
• 세션 기본 URL이 구성되지 않은 경우 (헤더와 환경 변수가 모두 없는 경우), argocdBaseUrl은 **필수 사항 (required)**입니다. 이 인자 없이 호출하면 에러가 반환됩니다.

각기 다른 토큰을 가진 여러 ArgoCD 인스턴스를 대상으로 하려면 토큰 레지스트리(token registry)를 구성하십시오. 토큰은 비밀 정보(secrets)이므로, 레지스트리는 환경 변수가 아닌 JSON 파일로부터 읽어옵니다. ARGOCD_TOKEN_REGISTRY_PATH를 해당 파일(예: 마운트된 Kubernetes secret)로 지정하십시오. 이렇게 하면 토큰이 프로세스 환경, 크래시 덤프(crash dumps) 및 자식 프로세스 상속(child-process inheritance)에 노출되지 않도록 유지할 수 있습니다.

ARGOCD_TOKEN_REGISTRY_PATH=/app/argocd-mcp/token-registry.json

파일은 기본 URL을 해당 URL에 사용해야 할 토큰과 매핑하는 JSON 배열을 포함합니다:

[
{ "baseUrl": "https://argo-a.example.com", "token": "<token-a>" },
{ "baseUrl": "https://argo-b.example.com", "token": "<token-b>" }
...

파일을 보안 처리하십시오. 서버 사용자에게만 제한하고(예: chmod 400), 디스크의 평문 파일(plaintext file)보다는 비밀 관리 메커니즘(Kubernetes secret volume, Vault agent 등)을 사용하는 것을 권장합니다.

로컬 개발. make run / make dev 타겟은 기본적으로 레지스트리 없이 실행됩니다. 레지스트리를 사용하려면 ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json을 전달하십시오. 파일을 dist/ 디렉토리 아래에 두지 마십시오. tsup은 clean: true 옵션과 함께 실행되며 매 빌드마다 해당 디렉토리를 삭제합니다. '로컬에서 실행하기(Running locally)'를 참조하십시오.

레지스트리가 구성되면, 호출자는 (비밀이 아닌) argocdBaseUrl 인자만 전달하여 인스턴스를 대상으로 지정하며, 서버는 이를 등록된 토큰과 쌍을 맞춥니다. 토큰은 도구 호출 페이로드(tool-call payload)에 절대 나타나지 않습니다.

서버는 두 가지 별개의 토큰 중 하나를 사용하여 호출을 해결합니다. 이 둘을 명확히 구분하는 것이 보안 모델을 작동하게 만드는 핵심입니다:

Default token	Registry token
Source	x-argocd-api-token 헤더 / ARGOCD_API_TOKEN 환경 변수 (세션 자격 증명)
Scope	기본 Base URL만 (x-argocd-base-url / ARGOCD_BASE_URL)
Used for	기본 Base URL을 대상으로 하는 호출
Never used for	기본 URL 이외의 모든 Base URL — 다른 호스트로는 절대 전송되지 않음

가장 중요한 규칙: 기본 토큰(default token)은 기본 Base URL에 결합되어 있으며, 그 외 모든 호스트의 토큰은 레지스트리(registry)에서 가져와야 합니다. 레지스트리 토큰은 정확히 해당 토큰이 등록된 호스트에만 결합됩니다.

특정 호출에 대해, 결정된 Base URL은 argocdBaseUrl 인자가 제공된 경우 해당 인자 값을 사용하며, 그렇지 않으면 세션 기본값을 사용합니다. 그 후 토큰은 다음과 같이 선택됩니다:

호출이 기본 Base URL을 대상으로 하는 경우 → **기본 토큰(default token)**을 사용합니다. 만약 기본 토큰이 제공되지 않았다면 (토큰이 없는 세션), 해당 Base URL에 대한 **레지스트리 토큰(registry token)**이 존재하는지 확인하여 폴백(fallback)으로 사용합니다.

호출이 다른 Base URL을 대상으로 하는 경우 → 해당 Base URL에 대한 **레지스트리 토큰(registry token)**만을 사용합니다. 이 경우 기본 토큰은 절대 사용되지 않습니다 — 기본 호스트 이외의 호스트로는 전송되지 않습니다.

• 만약 두 경우 모두 해당하지 않는다면 (요청된 Base URL에 대해 해결할 수 있는 토큰이 없다면), 호출은 "Missing required ArgoCD API token" 에러를 반환하며 해당 호스트로 어떠한 요청도 보내지 않습니다.

왜 기본 토큰이 기본 Base URL에 결합되어 있는가: argocdBaseUrl 인자는 도구 호출(tool call)로부터 오기 때문에, 호출자(또는 프롬프트 인젝션된 모델)가 이를 임의의 호스트로 지정할 수 있습니다. 만약 기본 토큰이 제공된 모든 Base URL과 쌍을 이룬다면, 해당 토큰은 Authorization: Bearer로서 전송될 것입니다.

header — 공격자의 호스트로 전송됩니다. 기본 토큰을 기본 Base URL로 제한하고, 그 외의 모든 호스트에 대해 명시적인 레지스트리(registry) 등록을 요구함으로써 이러한 토큰 유출(exfiltration)을 방지합니다. 추가 인스턴스를 대상으로 하려면 사전에 해당 토큰(및 호스트 이름)을 등록해야 합니다.

Base URL은 조회를 위해 정규화(host를 소문자로 변환, trailing slash 무시)되므로, 미세한 형식 차이가 있어도 일치하게 됩니다. 레지스트리가 구성되면, HTTP 전송 시 더 이상 연결 시점에 x-argocd-api-token을 요구하지 않습니다 — 호출 시마다 Base URL이 자체 토큰을 해결(resolve)하기 때문에 토큰 없는 연결이 허용됩니다. 만약 ARGOCD_TOKEN_REGISTRY_PATH가 설정되어 있지만 파일이 없거나, 읽을 수 없거나, 형식이 잘못된 경우, 서버는 fails closed(실패 시 차단)됩니다. 즉, 기본 자격 증명으로 조용히 되돌아가는 대신 시작 시점에 오류를 발생시키므로, 잘못 구성된 레지스트리가 잘못된 토큰으로 호출을 라우팅하는 일이 발생하지 않도록 합니다.

예를 들어, Base URL만 재정의(overriding)하는 tools/call 요청은 다음과 같습니다:

{
"jsonrpc": "2.0",
"id": 1,
...

Base URL을 다른 인스턴스로 재정의하려면 레지스트리 토큰이 필요합니다. 기본 토큰(x-argocd-api-token / ARGOCD_API_TOKEN)은 기본 Base URL에만 바인딩되며, 다른 호스트로는 절대 전송되지 않습니다. argocdBaseUrl을 기본 인스턴스(형식 차이를 제외하고 동일한 호스트)를 가리키도록 재정의하면 기본 토큰을 재사용합니다. 하지만 이를 다른 인스턴스로 지정하면 해당 인스턴스에 대한 레지스트리 토큰이 필요하며, 그렇지 않으면 호출은 "Missing required ArgoCD API token" 오류와 함께 실패하고 요청은 전송되지 않습니다. 이는 의도된 설계입니다 — 위에서 설명한 기본 토큰이 왜 기본 Base URL에 바인딩되는지 확인하십시오.

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

"MCP_READ_ONLY": "true"

이렇게 하면 다음 도구(tools)들이 비활성화됩니다:

create_application

update_application

delete_application

sync_application

run_resource_action

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

기본적으로 HTTP 전송 (HTTP transport) 방식은 각 클라이언트 연결에 세션 ID (session ID)를 할당하고 활성 세션의 인메모리 맵 (in-memory map)을 유지합니다. 이는 단일 인스턴스 배포 환경에서는 잘 작동하지만, 스티키 세션 (sticky sessions) 없이 여러 레플리카 (replicas)가 실행되는 경우에는 400 에러를 발생시킵니다. 다른 포드 (pod)로 라우팅된 요청은 원래 포드에서 생성된 세션을 찾을 수 없기 때문입니다.

세션 어피니티 (session affinity) 요구 사항 없이 실행하려면 --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

상태 비저장 (stateless) 모드에서는:

• Mcp-Session-Id가 반환되거나 요구되지 않습니다 — 어떤 레플리카라도 모든 요청을 처리할 수 있습니다. ArgoCD 인증 정보는 환경 변수 또는 x-argocd-base-url / x-argocd-api-token 헤더를 통해 매 요청마다 제공되어야 합니다 (기본 URL은 argocdBaseUrl 도구 인수를 통해 호출마다 재정의될 수 있지만, API 토큰은 항상 헤더 또는 환경 변수로만 제공됩니다). GET /mcp 및 DELETE /mcp는 405 Method Not Allowed를 반환합니다 (세션 수준의 SSE 및 종료는 지원되지 않습니다).

이 모드는 네트워크 수준의 스티키 세션 (sticky sessions)을 사용할 수 없는 수평 포드 오토스케일링 (Horizontal Pod Autoscaling, HPA) 환경의 Kubernetes 배포에 권장됩니다.

• 저장소 (repository)를 클론합니다:

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

• 프로젝트 의존성 (dependencies)을 설치합니다:

pnpm install

• 핫 리로딩 (hot reloading)이 활성화된 개발 서버를 시작합니다:

pnpm run dev

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

Makefile은 HTTP 전송을 통해 서버를 실행하기 위한 타겟 (targets)을 제공합니다:

make run # 빌드 후 HTTP 서버 실행 (프로덕션 스타일)
make dev # 핫 리로딩과 함께 소스에서 실행 (tsx watch)

기본적으로 두 타겟 모두 어떠한 자격 증명 (credentials)도 설정하지 않습니다. 즉, 서버는 기본 베이스 URL (base URL)이나 토큰 (token) 없이 시작되므로, 호출자는 요청마다 이를 제공해야 합니다 (x-argocd-base-url / x-argocd-api-token 헤더를 사용하거나, 레지스트리 (registry)가 구성된 경우 argocdBaseUrl 도구 인자 사용). 포트 (port) 또한 동일한 방식으로 재정의할 수 있습니다:

make run PORT=4000

자격 증명을 설정하려면 명령줄에서 관련 환경 변수 (environment variable)를 내보내기 (export) 하세요. 세 가지 옵션이 있으며 모두 선택 사항입니다:

변수	용도
ARGOCD_BASE_URL	호출 시 재정의하지 않을 때 사용되는 기본 ArgoCD 인스턴스 URL
ARGOCD_API_TOKEN	기본 베이스 URL에 대한 정적 API 토큰
ARGOCD_TOKEN_REGISTRY_PATH	베이스 URL을 토큰에 매핑하는 JSON 토큰 레지스트리 경로 (여러 인스턴스를 대상으로 하는 경우)

# 정적 베이스 URL + 토큰을 사용하는 단일 인스턴스:
make run ARGOCD_BASE_URL=https://argo.example.com ARGOCD_API_TOKEN=<token>
# 토큰 레지스트리를 통한 다중 인스턴스:
...