Servidor MCP de Argo CD

Una implementación de servidor del Protocolo de Contexto de Modelo (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 fluida con Visual Studio Code y otros clientes MCP a través de 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 en ArgoCD.

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 (logs) de las cargas de trabajo de la aplicación (Pods, Deployments, etc.).
get_resource_events: Obtiene eventos para 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 obtener 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 en modo Agente para utilizar el MCP.

Uso con VSCode

Siga la documentación sobre el 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 deshabilita la validación de certificados TLS para Node.js al conectarse a instancias de Argo CD que utilizan certificados autofirmados o certificados de CAs privadas que no son de confianza para el almacén de certificados de su sistema.

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

Modo de solo lectura

Si desea ejecutar el servidor MCP 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 (Stateless)

Por defecto, el transporte HTTP asigna un ID de sesión a cada conexión de cliente y mantiene un mapa en memoria de las sesiones activas. Esto funciona bien para despliegues de una sola instancia, pero provoca errores 400 cuando se ejecutan múltiples réplicas sin sesiones persistentes (sticky sessions), ya que una solicitud enrutada a un pod diferente no encontrará la sesión creada en el pod original.

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

node dist/index.js http --stateless

O con Docker:

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

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 a través de variables de entorno o encabezados x-argocd-base-url / x-argocd-api-token.
GET /mcp y DELETE /mcp devuelven 405 Method Not Allowed (no se admiten SSE a nivel de sesión ni terminación).

Este modo se recomienda para despliegues en Kubernetes con escalado automático de pods horizontal (HPA) donde no hay sesiones persistentes a nivel de red 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.

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 desde la página de lanzamientos de ArgoCD; por ejemplo, aquí está el enlace a 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 necesarios desde el archivo src/types/argocd.d.ts recién generado. Este paso a menudo requiere una revisión manual para garantizar que solo se expongan los tipos necesarios.

Créditos

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

Argo CD MCP Server