ArgoCD MCP — Casos de uso, Instalar & Demo en vivo

Por qué usarlo

Características clave

Lista/inspecciona aplicaciones de ArgoCD en todos los proyectos
Muestra estado de sincronización, salud e información de última sincronización
Compara estado actual del cluster vs estado deseado en git
Dispara sincronización (con opciones de prune/force) cuando estés autorizado
Lee manifiestos de aplicaciones sin acceso directo a kubectl en el cluster

Demo en vivo

Cómo se ve en la práctica

argocd.replay ▶ listo

0/0

Instalar

Elige tu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  }
}

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  }
}

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "argocd",
      "command": "uvx",
      "args": [
        "mcp-for-argocd"
      ]
    }
  ]
}

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json

{
  "context_servers": {
    "argocd": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-for-argocd"
        ]
      }
    }
  }
}

Añádelo a context_servers. Zed recarga en caliente al guardar.

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

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: ArgoCD

Encuentra aplicaciones de ArgoCD que se han desincronizado

👤 Equipos de Platform / SRE ejecutando GitOps ⏱ ~20 min intermediate

Cuándo usarlo: Semanalmente: ¿qué aplicaciones en qué clusters están OutOfSync o Degraded y por qué?

Requisitos previos

Token de API de ArgoCD con permiso de lectura — argocd account generate-token --account <read-only-user>
URL del servidor ArgoCD — ARGOCD_SERVER=argocd.my.company.com

Flujo

Lista aplicaciones con estado

Lista todas las aplicaciones de ArgoCD. Para cada una: nombre, proyecto, estado de sincronización, estado de salud, hora de última sincronización.✓ Copiado

→ Inventario completo
Enfócate en la desincronización

Filtra a aplicaciones con syncStatus != 'Synced' o health != 'Healthy'. Ordena por tiempo desde la última sincronización.✓ Copiado

→ Lista de aplicaciones problemáticas
Compara una aplicación específica

Para la aplicación <name>, muestra la comparación entre deseado (git) y actual. ¿Qué recursos están desincronizados?✓ Copiado

→ Comparación a nivel de recursos

Resultado: Un reporte semanal de desincronización identificando qué aplicaciones necesitan atención y por qué.

Errores comunes

Desincronización causada por un recurso legítimo solo en tiempo de ejecución (p.ej. réplicas escaladas por HPA) — Configura ignoreDifferences en la especificación de Application para excluir campos que cambian en tiempo de ejecución

Combinar con: notion

Revisa y aplica una sincronización para una aplicación específica

👤 Ingenieros de DevOps promoviendo cambios ⏱ ~15 min intermediate

Cuándo usarlo: Se fusionó un PR en main; ArgoCD muestra la aplicación como OutOfSync esperando tu aprobación.

Requisitos previos

Token con permiso de sincronización en el proyecto destino — Rol con permiso applications, sync, <project>/*

Flujo

Inspecciona el cambio pendiente

Para la aplicación <name>, muestra la comparación. ¿Qué recursos cambian, cuál es el radio de impacto?✓ Copiado

→ Comparación concreta
Verifica el commit origen

¿A qué SHA de commit apunta el estado deseado? Muestra el mensaje de commit en GitHub y el PR.✓ Copiado

→ Contexto de Commit + PR
Sincroniza con prune=false primero

Dispara sincronización para <name> con prune=false, dryRun=false. Espera a completarse, muestra estado final.✓ Copiado

→ Sincronización exitosa; salud Healthy

Resultado: Un despliegue con revisión previa, no una sorpresa; la eliminación por prune solo ocurre explícitamente.

Errores comunes

Sincronizar con prune=true puede eliminar recursos que aún necesitas — Siempre comienza con prune=false; solo habilita prune cuando hayas confirmado que no existen recursos creados manualmente en el namespace

Combinar con: github

Reversión de emergencia a una revisión anterior de git

👤 SREs durante un incidente de mal despliegue ⏱ ~15 min advanced

Cuándo usarlo: Un despliegue salió, los errores se dispararon y necesitas revertir a la última versión conocida como buena.

Flujo

Obtén revisión actual + historial

Para la aplicación <name>, muestra revisión actual y las últimas 5 revisiones desplegadas con timestamps.✓ Copiado

→ Tabla de historial
Elige el objetivo de reversión

¿Cuál fue la revisión hace 2 sincronizaciones? Confirma que su SHA coincida con el commit de git antes de que comenzara el incidente.✓ Copiado

→ SHA objetivo identificado
Revierte

Sincroniza <name> a la revisión <SHA> con prune=false. Observa hasta que sea Healthy. Publica en Teams cuando termines.✓ Copiado

→ Aplicación revertida + notificación enviada

Resultado: Una reversión limpia con un registro de auditoría, típicamente en menos de 5 minutos.

Errores comunes

Revertir solo la aplicación pero la migración de DB ya se ejecutó hacia adelante — Las migraciones de DB necesitan su propio plan de reversión; a veces 'avanzar' con un fix es más seguro que revertir código contra un esquema mutado

Combinar con: sentry · ms-teams

Construye un inventario de aplicaciones entre clusters

👤 Equipos de plataforma gestionando muchos clusters ⏱ ~20 min intermediate

Cuándo usarlo: Ejecutas ArgoCD en un modelo hub-spoke y quieres una lista plana: 'qué aplicaciones se ejecutan dónde'.

Flujo

Lista clusters que ArgoCD gestiona

Lista todos los clusters registrados en ArgoCD con su nombre y URL de servidor.✓ Copiado

→ Inventario de clusters
Mapea aplicaciones a clusters

Para cada aplicación, muestra su cluster destino y namespace. Agrupa por cluster.✓ Copiado

→ Lista de aplicaciones por cluster
Marca ubicaciones inusuales

¿Hay alguna aplicación desplegada en un cluster inesperado (p.ej. aplicación 'solo-prod' en un cluster dev)? Marca con razón.✓ Copiado

→ Lista de anomalías

Resultado: Un mapa actualizado de qué se ejecuta dónde, útil para auditorías y planificación de capacidad.

Errores comunes

Entradas de cluster obsoletas — secretos eliminados pero cluster aún listado — Periódicamente verifica que cada cluster sea alcanzable; elimina los obsoletos

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

argocd + github

Referencia cruzada de sincronización de Argo con el PR que la causó

Para la aplicación <name>, muestra el SHA de revisión actual; obtén el PR de GitHub que lo introdujo y resume el cambio.✓ Copiado

argocd + sentry

Correlaciona una sincronización de Argo con un pico de errores post-despliegue

La aplicación <name> sincronizó a las 14:02; ¿se dispararon errores de Sentry después? Si es sí, muestra el top issue introducido.✓ Copiado

argocd + ms-teams

Publica eventos de sincronización/reversión a un canal de Teams

Después de cualquier sincronización manual de la aplicación <name>, publica un mensaje en Teams #deploys con el SHA de revisión y quién lo disparó.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
list_applications	project?, selector?	Inventario de aplicaciones	free
get_application	name	Estado detallado de una aplicación específica	free
get_application_diff	name, revision?	Previsualiza qué cambiaría una sincronización	free
sync_application	name, revision?, prune?, dryRun?, resources?	Aplica cambios pendientes	free (triggers cluster work)
get_application_resource_tree	name	Inspecciona los recursos activos que posee una aplicación	free
list_clusters		Inventario entre clusters	free

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: Limitado por la capacidad de tu servidor ArgoCD; límite práctico ~10 req/s
Tokens por llamada: Lista de aplicaciones: 500–3000 tokens. Comparación: hasta 5000.
Monetario: Gratuito — ArgoCD es código abierto, solo pagas por la infraestructura que lo aloja.
Consejo: Cachea lista de aplicaciones; usa selectores (project, label) para acotar consultas en lugar de listar todo.

Seguridad

Permisos, secretos, alcance

Ámbitos mínimos: lectura en aplicaciones, clusters para sesiones de solo lectura

Almacenamiento de credenciales: ARGOCD_AUTH_TOKEN y ARGOCD_SERVER en env

Salida de datos: Llamadas solo a tu servidor ArgoCD

No conceder nunca: admin sincronización en todos los proyectos sin razón account:update

El permiso de sincronización puede desplegar manifiestos arbitrarios — trátalo como acceso de escritura en producción.
Usa políticas RBAC con scope de proyecto en lugar de cluster-admin para cuentas de automatización.

Resolución de problemas

Errores comunes y soluciones

401 Unauthenticated

ARGOCD_AUTH_TOKEN expiró o fue revocado. Regenera con argocd account generate-token.

Verificar: argocd account get-user-info --auth-token $ARGOCD_AUTH_TOKEN

403 Permission denied on sync

El rol carece del permiso applications, sync, <project>/*. Actualiza AppProject o el rol de la cuenta.

Sync stuck in Progressing for >10 min

Usualmente un recurso atrapado — verifica el árbol de recursos para un hook fallido o un controlador atrapado; puede necesitar intervención manual en el cluster.

Diff shows unexpected drift on every sync

Controladores mutando campos en tiempo de ejecución. Añade ignoreDifferences a la especificación de Application para esos campos.

Alternativas

ArgoCD vs otros

Alternativa	Cuándo usarla	Contrapartida
Flux MCP	Usas Flux en lugar de ArgoCD para GitOps	Motor GitOps diferente; modelo CLI-first
Kubernetes MCP (raw kubectl)	Quieres acceso directo al cluster sin abstracción de GitOps	Imperativo — derrota el propósito de GitOps para aplicaciones gestionadas

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills