Argo CD

Interactúa con aplicaciones de Argo CD mediante lenguaje natural.

Documentación

Servidor MCP de Argo CD

Una implementación de un servidor Model Context Protocol (MCP) para Argo CD, que permite a los asistentes de IA interactuar con sus aplicaciones de Argo CD mediante lenguaje natural. Este servidor permite una integración perfecta con Visual Studio Code y otros clientes MCP a través de los protocolos de transporte stdio y flujo HTTP.

argocd-mcp-demo

Características

Protocolos de transporte: Admite modos de transporte stdio y flujo HTTP para una integración flexible con diferentes clientes
Integración completa con la API de Argo CD: Proporciona acceso integral a los recursos y operaciones de Argo CD
Listo para asistentes de IA: Herramientas preconfiguradas para que los asistentes de IA interactúen con Argo CD en lenguaje natural

Herramientas disponibles

El servidor proporciona las siguientes herramientas de gestión de ArgoCD:

Gestión de clústeres

list_clusters: Lista todos los clústeres registrados con ArgoCD

Gestión de proyectos

get_appproject: Obtiene información detallada sobre un AppProject (proyecto) específico

Gestión de aplicaciones

list_applications: Lista y filtra todas las aplicaciones
get_application: Obtiene información detallada sobre una aplicación específica
create_application: Crea una nueva aplicación
update_application: Actualiza una aplicación existente
delete_application: Elimina una aplicación
sync_application: Activa una operación de sincronización en una aplicación

Gestión de recursos

get_application_resource_tree: Obtiene el árbol de recursos de una aplicación específica
get_application_managed_resources: Obtiene los recursos gestionados de una aplicación específica
get_application_workload_logs: Obtiene los registros de las cargas de trabajo de la aplicación (Pods, Deployments, etc.)
get_resource_events: Obtiene los eventos de los recursos gestionados por una aplicación
get_resource_actions: Obtiene las acciones disponibles para los recursos
run_resource_action: Ejecuta una acción en un recurso

Instalación

Requisitos previos

Node.js (se recomienda v18 o superior)
Gestor de paquetes pnpm (para desarrollo)
Instancia de Argo CD con acceso a la API
Token de API de Argo CD (consulte la documentación para instrucciones)

Uso con Cursor

Siga la documentación de Cursor para soporte MCP y cree un archivo .cursor/mcp.json en su proyecto:

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

Inicie una conversación con el modo Agente para usar el MCP.

Uso con VSCode

Siga la documentación de Uso de servidores MCP en VS Code y cree un archivo .vscode/mcp.json en su proyecto:

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

Inicie una conversación con un asistente de IA en VS Code que admita MCP.

Uso con Claude Desktop

Siga la documentación de MCP en Claude Desktop y cree un archivo de configuración 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>"
      }
    }
  }
}

Configure Claude Desktop para usar este archivo de configuración en los ajustes.

Certificados autofirmados

Si su instancia de Argo CD utiliza certificados autofirmados o certificados de una Autoridad de Certificación (CA) privada, es posible que deba agregar la siguiente variable de entorno a su configuración:

"NODE_TLS_REJECT_UNAUTHORIZED": "0"

Esto desactiva la validación de certificados TLS para Node.js al conectarse a instancias de Argo CD que utilizan certificados autofirmados o certificados de CA privadas que no son de confianza para el almacén de certificados de su sistema.

Advertencia: Deshabilitar la verificación SSL reduce la seguridad. Use esta configuración solo en entornos de desarrollo o cuando comprenda las implicaciones de seguridad.

Proporcionar credenciales de ArgoCD

El servidor se conecta a ArgoCD usando una URL base y un token de API.

Token de API — solo encabezado / variable de entorno (obligatorio)

El token de API de ArgoCD es un secreto y solo se lee desde la capa de transporte, nunca desde un argumento de llamada a herramienta:

Encabezados HTTP (solo transporte HTTP): x-argocd-api-token.
Variables de entorno: ARGOCD_API_TOKEN (todos los transportes).

Este token es solo de salida: autentica este servidor ante ArgoCD y nunca autoriza a un llamante entrante. Consulte Exposición de red para saber quién puede alcanzar el listener.

Este es el token predeterminado. Es obligatorio a menos que se configure un registro de tokens: en el transporte HTTP, una conexión que no proporcione token (ni encabezado ni variable de entorno) se rechaza con 400 Bad Request, pero cuando se configura un registro, se permite una conexión sin token porque cada llamada resuelve su propio token de registro. Mantener el token fuera de los argumentos de las herramientas garantiza que nunca entre en prompts, contexto del modelo o registros de llamadas a herramientas.

URL base — encabezado / variable de entorno, o argumento por llamada

La URL base puede proporcionarse a nivel de sesión (se resuelve una vez cuando el servidor se inicia o cuando un cliente HTTP se conecta):

Encabezados HTTP (solo transporte HTTP): x-argocd-base-url.
Variables de entorno: ARGOCD_BASE_URL (todos los transportes).

Además, cada herramienta acepta un argumento opcional argocdBaseUrl:

Si existe una URL base predeterminada de sesión, argocdBaseUrl es opcional y anula la predeterminada para esa única llamada.
Si no se configura una URL base predeterminada de sesión (tanto el encabezado como la variable de entorno están ausentes), argocdBaseUrl es obligatorio; una llamada sin él devuelve un error.

Registro de tokens — tokens por URL base (multi-instancia)

Para apuntar a múltiples instancias de ArgoCD, cada una con su propio token, configure un registro de tokens. Debido a que los tokens son secretos, el registro se lee desde un archivo JSON, no desde una variable de entorno — apunte ARGOCD_TOKEN_REGISTRY_PATH al archivo (por ejemplo, un secreto de Kubernetes montado). Esto mantiene los tokens fuera del entorno del proceso, los volcados de memoria y la herencia de procesos secundarios.

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

El archivo contiene una matriz JSON que asigna una URL base al token que debe usarse para ella:

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

Asegure el archivo. Restrinja el acceso al usuario del servidor (por ejemplo, chmod 400) y prefiera un mecanismo de gestión de secretos (volumen de secreto de Kubernetes, agente de Vault, etc.) en lugar de un archivo de texto plano en disco.

Desarrollo local. Los objetivos make run / make dev se ejecutan sin un registro de forma predeterminada; pase ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json para usar uno. No coloque el archivo bajo dist/ — tsup se ejecuta con clean: true y borra ese directorio en cada compilación. Consulte Ejecución local.

Con un registro configurado, un llamante apunta a una instancia pasando solo el argumento (no secreto) argocdBaseUrl; el servidor lo empareja con el token registrado. El token nunca aparece en la carga útil de la llamada a herramienta.

Dos tipos de token

El servidor resuelve las llamadas usando uno de dos tokens distintos. Mantenerlos claros es lo que hace funcionar el modelo de seguridad:

	Token predeterminado	Token de registro
Fuente	Encabezado `x-argocd-api-token` / variable de entorno `ARGOCD_API_TOKEN` (la credencial de sesión)	Una entrada `token` en el archivo JSON `ARGOCD_TOKEN_REGISTRY_PATH`, claveada por `baseUrl`
Alcance	Solo la URL base predeterminada (`x-argocd-base-url` / `ARGOCD_BASE_URL`)	La URL base específica a la que está claveada su entrada
Usado para	Una llamada que apunta a la URL base predeterminada	Una llamada que apunta a cualquier URL base presente en el registro (incluida la predeterminada, como respaldo)
Nunca usado para	Cualquier URL base que no sea la predeterminada — nunca se envía a un host diferente	Cualquier URL base no registrada

La regla cardinal: el token predeterminado está vinculado a la URL base predeterminada; el token de cualquier otro host debe provenir del registro. Un token de registro está vinculado exactamente al host bajo el cual está registrado.

Orden de resolución

Para una llamada dada, la URL base resuelta es el argumento argocdBaseUrl si se proporciona, de lo contrario, la predeterminada de sesión. El token se elige entonces por:

La llamada apunta a la URL base predeterminada → use el token predeterminado. Si no se proporcionó un token predeterminado (sesión sin token), recurra al token de registro para esa URL base, si existe.
La llamada apunta a cualquier otra URL base → use el token de registro solo para esa URL base. El token predeterminado nunca se usa aquí — no se envía a un host que no sea el predeterminado.
Si ninguno aplica (no se puede resolver un token para la URL base solicitada), la llamada devuelve un error de "Falta el token de API de ArgoCD requerido" y no se realiza ninguna solicitud a ese host.

Por qué el token predeterminado está vinculado a la URL base predeterminada. El argumento argocdBaseUrl proviene de la llamada a herramienta, por lo que un llamante (o un modelo inyectado por prompt) podría apuntarlo a un host arbitrario. Si el token predeterminado se emparejara con cualquier URL base proporcionada, ese token se enviaría — como encabezado Authorization: Bearer — al host del atacante. Restringir el token predeterminado a la URL base predeterminada, y requerir una entrada explícita en el registro para cualquier otro host, evita esta exfiltración de tokens. Para apuntar a instancias adicionales, debe registrar sus tokens (y por lo tanto sus nombres de host) de antemano.

Las URL base se normalizan para la búsqueda (host en minúsculas, se ignoran las barras finales), por lo que diferencias menores de formato aún coinciden. Cuando se configura un registro, el transporte HTTP ya no requiere x-argocd-api-token en el momento de la conexión — se permite una conexión sin token porque la URL base por llamada resuelve su propio token. Si ARGOCD_TOKEN_REGISTRY_PATH está configurado pero el archivo falta, no se puede leer o está malformado, el servidor falla de forma segura: lanza una excepción al inicio en lugar de recurrir silenciosamente a su credencial predeterminada, por lo que un registro mal configurado nunca puede causar que las llamadas se enruten con el token incorrecto.

Por ejemplo, una solicitud tools/call que anula solo la URL base:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_applications",
    "arguments": {
      "argocdBaseUrl": "https://argocd.other-cluster.example.com"
    }
  }
}

Anular la URL base a una instancia diferente requiere un token de registro. El token predeterminado (x-argocd-api-token / ARGOCD_API_TOKEN) está vinculado solo a la URL base predeterminada y nunca se envía a un host diferente. Anular argocdBaseUrl para apuntar a la instancia predeterminada (mismo host, formato aparte) reutiliza el token predeterminado; apuntarlo a cualquier otra instancia requiere un token de registro para esa instancia, de lo contrario la llamada falla con "Falta el token de API de ArgoCD requerido" y no se envía ninguna solicitud. Esto es intencional — consulte por qué el token predeterminado está vinculado a la URL base predeterminada arriba.

Exposición de red

Los transportes http y sse abren un listener de red que alcanza todas las herramientas de ArgoCD, incluyendo create_application, delete_application, sync_application y run_resource_action. Por defecto, se vincula solo a loopback.

ARGOCD_API_TOKEN no lo protege. Ese token autentica este servidor ante ArgoCD. No dice nada sobre quién es el llamante. El acceso entrante se controla mediante los ajustes a continuación.

Ajuste	Flag	Variable de entorno	Predeterminado	Qué hace
Dirección de enlace	`--bind-address`	`MCP_BIND_ADDRESS`	`127.0.0.1`	Qué dirección acepta conexiones el listener.
Token entrante	—	`MCP_AUTH_TOKEN`	sin establecer	Cuando se establece, cada solicitud debe llevar `Authorization: Bearer <token>`.
`Host` permitidos	`--allowed-host-header`	—	nombres de loopback	Nombre de host adicional aceptado en el encabezado `Host` de una solicitud. Repetir por nombre.
`Origin` permitidos	`--allowed-origin`	—	orígenes de loopback	Origen de navegador adicional aceptado en el encabezado `Origin` de una solicitud. Repetir por origen.
Autenticación externa	`--allow-unauthenticated`	—	`false`	Permite un enlace no loopback sin token, cuando algo delante ya autentica a los llamantes.
Puerto	`--port`	—	`3000`	En qué puerto escuchar.

--bind-address decide quién puede conectarse. --allowed-host-header solo verifica lo que un cliente ya conectado afirma. No son un par, y el segundo no es un firewall.

Los flags sin variable de entorno se pasan como argumentos, también en un contenedor: docker run <image> http --allow-unauthenticated.

Comportamiento:

Ampliar el bind requiere MCP_AUTH_TOKEN o --allow-unauthenticated. De lo contrario, el servidor registra el motivo y sale con un código distinto de cero en lugar de iniciarse expuesto.
Origin siempre se verifica, en esquema, host y puerto. Esto es lo que detiene a una página web maliciosa, incluida una que use DNS rebinding.
Host se verifica en un bind de loopback, o en cualquier bind con al menos un --allowed-host-header. De lo contrario, el hostname que los clientes usan legítimamente es desconocido, por lo que la verificación se omite y se registra una advertencia.
GET /healthz está exento, por lo que una sonda de kubelet aún tiene éxito. Solo devuelve liveness.
La configuración no utilizable falla al inicio con el motivo, en lugar de ser ignorada.
Modo de solo lectura es independiente de todo esto y limita lo que cualquier llamador puede hacer.

Exponer el listener deliberadamente:

export MCP_AUTH_TOKEN=<inbound_token>
node dist/index.js http --bind-address 0.0.0.0 --allowed-host-header mcp.internal.example.com

La imagen del contenedor mantiene el mismo valor predeterminado de loopback, por lo que no necesita configuración adicional cuando el llamador comparte su namespace de red, como un sidecar en el mismo pod de Kubernetes:

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

Para publicar un puerto, amplíe el bind y establezca una credencial de entrada:

docker run -p 3000:3000 \
  -e ARGOCD_BASE_URL=<argocd_url> -e ARGOCD_API_TOKEN=<argocd_token> \
  -e MCP_BIND_ADDRESS=0.0.0.0 -e MCP_AUTH_TOKEN=<inbound_token> \
  argoprojlabs/mcp-for-argocd

Cuando el bind se amplía y un proxy o mesh ya autentica a los llamadores, use --allow-unauthenticated en lugar de MCP_AUTH_TOKEN.

Consulte Notas del operador para las advertencias de implementación.

Modo de solo lectura

Si desea ejecutar el MCP Server en modo de solo lectura para evitar la modificación de recursos o aplicaciones, debe establecer la variable de entorno:

"MCP_READ_ONLY": "true"

Esto deshabilitará las siguientes herramientas:

create_application
update_application
delete_application
sync_application
run_resource_action

Por defecto, todas las herramientas estarán disponibles.

Modo sin estado

Por defecto, el transporte HTTP asigna un ID de sesión a cada conexión de cliente y mantiene un mapa en memoria de sesiones activas. Esto funciona bien para implementaciones de una sola instancia, pero causa errores de 400 cuando se ejecutan múltiples réplicas sin sesiones fijas, porque una solicitud enrutada a un pod diferente no encontrará la sesión que se creó en el pod original.

Para ejecutar sin requisitos de afinidad de sesión, inicie el servidor con el flag --stateless:

node dist/index.js http --stateless

O con Docker:

docker run -p 3000:3000 \
  -e ARGOCD_BASE_URL=<argocd_url> -e ARGOCD_API_TOKEN=<argocd_token> \
  -e MCP_BIND_ADDRESS=0.0.0.0 -e MCP_AUTH_TOKEN=<inbound_token> \
  argoprojlabs/mcp-for-argocd http --stateless

La imagen tiene un ENTRYPOINT, por lo que sobrescribir el comando reemplaza solo los argumentos. Publicar un puerto es lo que hace necesario el bind más amplio y el token de entrada aquí; consulte Exposición de red.

En modo sin estado:

No se devuelve ni se requiere Mcp-Session-Id — cualquier réplica puede manejar cualquier solicitud
Las credenciales de ArgoCD deben proporcionarse en cada solicitud mediante variables de entorno o encabezados x-argocd-base-url / x-argocd-api-token (la URL base también puede sobrescribirse por llamada mediante el argumento de herramienta argocdBaseUrl; el token de API siempre es solo de encabezado/env)
GET /mcp y DELETE /mcp devuelven 405 Method Not Allowed (SSE a nivel de sesión y terminación no son compatibles)

Este modo se recomienda para implementaciones de Kubernetes con autoscaling horizontal de pods (HPA) donde las sesiones fijas a nivel de red no están disponibles.

Para desarrollo

Clone el repositorio:

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

Instale las dependencias del proyecto:

pnpm install

Inicie el servidor de desarrollo con recarga en caliente habilitada:

pnpm run dev

Una vez que el servidor esté en ejecución, puede utilizar el servidor MCP dentro de Visual Studio Code u otro cliente MCP.

Ejecución local

El Makefile proporciona objetivos para ejecutar el servidor sobre el transporte HTTP:

make run    # build, then run the HTTP server (production-style)
make dev    # run from source with hot reloading (tsx watch)

Por defecto, ningún objetivo establece credenciales — el servidor se inicia sin URL base ni token predeterminados, por lo que los llamadores deben proporcionarlos por solicitud (encabezados x-argocd-base-url / x-argocd-api-token, o el argumento de herramienta argocdBaseUrl una vez que se configura un registro). Sobrescriba el puerto de la misma manera:

make run PORT=4000

Para configurar credenciales, exporte la variable de entorno relevante en la línea de comandos. Hay tres (todas opcionales):

Variable	Propósito
`ARGOCD_BASE_URL`	URL de instancia de ArgoCD predeterminada utilizada cuando una llamada no la sobrescribe.
`ARGOCD_API_TOKEN`	Token de API estático para la URL base predeterminada.
`ARGOCD_TOKEN_REGISTRY_PATH`	Ruta a un registro de tokens JSON que mapea URLs base a tokens (para apuntar a múltiples instancias).

Estas son todas credenciales de salida. Para quién puede alcanzar el listener, consulte Exposición de red.

# Single instance with a static base URL + token:
make run ARGOCD_BASE_URL=https://argo.example.com ARGOCD_API_TOKEN=<token>

# Multiple instances via a token registry:
make run ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json

# Both — a default instance plus extra instances resolved from the registry:
make dev ARGOCD_BASE_URL=https://argo.example.com ARGOCD_API_TOKEN=<token> \
  ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json

Consulte Resolución de tokens para saber cómo interactúan el token predeterminado y el registro. Si ARGOCD_TOKEN_REGISTRY_PATH está establecido pero el archivo falta, no se puede leer o está malformado, el servidor falla de forma segura al inicio.

Mantenga los tokens fuera de su historial de shell. Pasar ARGOCD_API_TOKEN=<token> directamente en la línea de comandos de make registra el secreto en su historial de shell y lo expone en la lista de procesos. Prefiera exportarlo en el shell primero para que nunca aparezca en la invocación de make:
export ARGOCD_API_TOKEN=<token>
make run ARGOCD_BASE_URL=https://argo.example.com
Una ruta de registro (ARGOCD_TOKEN_REGISTRY_PATH) y una URL base no son secretos, por lo que está bien pasarlos en línea.

No coloque el archivo de registro bajo dist/ — tsup compila con clean: true y borra ese directorio en cada compilación.

El servidor HTTP escucha en POST /mcp (127.0.0.1:3000 por defecto, consulte Exposición de red para ampliarlo) con un endpoint de liveness GET /healthz. Para enviar una solicitud, primero initialize una sesión (capture el encabezado de respuesta mcp-session-id), luego llame a una herramienta, pasando una de las URLs base registradas como argumento argocdBaseUrl:

# 1. Initialize a session — note the mcp-session-id response header
curl -sD - http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

# 2. Call a tool, reusing that session id
curl -s http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'mcp-session-id: <session-id-from-step-1>' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_applications","arguments":{"argocdBaseUrl":"https://argo-a.example.com"}}}'

Para evitar administrar un ID de sesión, ejecute en modo sin estado (node dist/index.js http --stateless) para que cada POST /mcp sea autocontenido.

Actualización de tipos de ArgoCD

Para actualizar las definiciones de tipos de TypeScript basadas en la especificación más reciente de la API de Argo CD:

Descargue el archivo swagger.json de la página de lanzamiento de ArgoCD, por ejemplo, aquí está el enlace swagger.json para ArgoCD v2.14.11.
Coloque el archivo swagger.json descargado en el directorio raíz del proyecto argocd-mcp.
Genere los tipos de TypeScript a partir de la definición de Swagger ejecutando el siguiente comando. Esto creará o sobrescribirá el archivo src/types/argocd.d.ts:
```
pnpm run generate-types
```
Actualice el archivo src/types/argocd-types.ts para exportar los tipos requeridos del src/types/argocd.d.ts recién generado. Este paso a menudo requiere revisión manual para asegurar que solo se expongan los tipos necesarios.

Créditos

El proyecto fue creado y donado inicialmente por @jiachengxu, @imwithye, @hwwn y @alexmt de Akuity.