ArgoCD

argocd-mcp

Toda la API de ArgoCD, expuesta a los LLMs mediante MCP.
103+ endpoints. Cero handlers hardcodeados. Dos modos: búsqueda o herramientas generadas.

Inicio Rápido • Cómo Funciona • OAuth • OIDC • Configuración

La mayoría de los servidores MCP de ArgoCD hardcodean unas pocas operaciones: listar aplicaciones, sincronizar, obtener estado. Cuando ArgoCD añade una nueva funcionalidad, esperas a que el mantenedor la agregue.

argocd-mcp adopta un enfoque diferente, inspirado en el servidor MCP de Cloudflare que cubre más de 2500 endpoints con solo 2 herramientas. Lee la especificación OpenAPI de ArgoCD al iniciar y expone cada endpoint a través de solo 2 herramientas: search y execute. ¿Nueva versión de ArgoCD? Reinicia el servidor. Listo.

• 103+ endpoints de la especificación OpenAPI de ArgoCD, cero handlers hardcodeados
• Dos modos de herramientas: search (2 meta-herramientas) o generated (1 herramienta tipada por endpoint)
• Funciona con Claude Desktop, Claude Code, Cursor o cualquier cliente MCP
• Sin código por endpoint — la especificación OpenAPI es la fuente de verdad
• Tres modos de autenticación: token estático, OAuth mediante ArgoCD Dex, u OAuth mediante el proveedor OIDC externo en el que ArgoCD confía (ambos otorgan RBAC por usuario)
• Modo de solo lectura — desactiva todas las operaciones de escritura con una sola bandera
• Delimitación de recursos — restringe qué recursos de ArgoCD se exponen con ALLOWED_RESOURCES
• Límite de tasa — token bucket por usuario para proteger a ArgoCD de llamadas excesivas
• Plantillas de prompts — flujos de trabajo preempaquetados para operaciones comunes (aplicaciones no saludables, diff, rollback, logs)
• Registro de auditoría — logs JSON estructurados para cada llamada de herramienta (usuario, método, ruta, estado, duración)
• Anotaciones MCP — las herramientas se anotan como de solo lectura, destructivas o idempotentes para una categorización adecuada del cliente
• Búsqueda semántica opcional mediante embeddings de Ollama

Cómo Funciona

Al iniciar, el servidor obtiene la especificación Swagger de ArgoCD y analiza cada endpoint. Luego los expone a los LLMs mediante uno de dos modos:

Modo de búsqueda (predeterminado, TOOL_MODE=search)

Dos meta-herramientas manejan los 103+ endpoints. El LLM descubre endpoints buscando y luego los llama mediante un ejecutor genérico.

graph TD
    A[ArgoCD /swagger.json] -->|Fetch at startup| B[Parse Swagger 2.0]
    B --> C[103+ Endpoints in memory]
    C --> D[search_operations]
    C --> E[execute_operation]
    D -->|LLM discovers endpoints| F[Returns method, path, summary, params]
    E -->|LLM calls API| G[Proxies to ArgoCD with user token]

Modo generado (TOOL_MODE=generated)

Una herramienta MCP tipada por endpoint, generada dinámicamente al iniciar. El LLM llama a argocd_application_sync(name, revision) directamente — sin paso de búsqueda, sin construcción de ruta.

graph TD
    A[ArgoCD /swagger.json] -->|Fetch at startup| B[Parse Swagger 2.0]
    B --> C[103+ Endpoints]
    C -->|Generate per endpoint| D[argocd_application_list]
    C --> E[argocd_application_sync]
    C --> F[argocd_cluster_get]
    C --> G[... 100+ more tools]
    D & E & F & G -->|Typed params, 1 call| H[Proxies to ArgoCD]

¿Qué modo elegir?

Clientes como Claude Code y Claude Desktop admiten carga diferida de herramientas — solo cargan las definiciones de herramientas en el contexto cuando es necesario, por lo que las 103+ herramientas no consumen la ventana de contexto por adelantado.

Inicio Rápido

Gráfico Helm (Kubernetes)

helm install argocd-mcp oci://ghcr.io/matthisholleville/charts/argocd-mcp \
  --set argocd.baseURL=https://argocd.example.com \
  --set argocd.token=your-token

Consulta todas las opciones de configuración en charts/argocd-mcp/values.yaml.

Token Estático (simple)

Ideal para desarrollo local, CI/CD o configuraciones de un solo usuario. Utiliza un token de API estático de ArgoCD.

Claude Code

claude mcp add argocd -s user -- \
  docker run --rm -i \
  -e ARGOCD_BASE_URL=https://argocd.example.com \
  -e ARGOCD_TOKEN=your-token \
  ghcr.io/matthisholleville/argocd-mcp:latest

Claude Desktop

Añade a tu configuración MCP de Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "argocd": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
        "-e", "ARGOCD_BASE_URL=https://argocd.example.com",
        "-e", "ARGOCD_TOKEN=your-token",
        "ghcr.io/matthisholleville/argocd-mcp:latest"
      ]
    }
  }
}

OAuth mediante ArgoCD Dex (RBAC por usuario)

Ideal para configuraciones multiusuario y de producción. Cada usuario se autentica con su propia identidad mediante el Dex integrado de ArgoCD. No se necesita token estático — el id_token de Dex del usuario se reenvía a ArgoCD, que aplica sus políticas RBAC por usuario.

Paso 1: Inicia el servidor

docker run -p 8080:8080 \
  -e ARGOCD_BASE_URL=https://argocd.example.com \
  -e MCP_TRANSPORT=http \
  -e AUTH_MODE=oauth \
  -e DEX_CLIENT_ID=argo-cd-cli \
  -e SERVER_BASE_URL=http://localhost:8080 \
  ghcr.io/matthisholleville/argocd-mcp:latest

Paso 2: Conecta tu cliente MCP

Claude Code

claude mcp add --transport http --callback-port 9382 argocd http://localhost:8080/mcp

Luego ejecuta /mcp dentro de Claude Code para autenticarte mediante el navegador.

Claude Desktop

Claude Desktop requiere una URL de acceso público (la redirección OAuth pasa por claude.ai). Expón el servidor mediante un proxy inverso o ngrok, luego configura SERVER_BASE_URL en consecuencia. En modo oidc, esa devolución de llamada no es una URL de bucle local, por lo que también debe estar en la lista de permitidos: OIDC_ALLOWED_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback.

Añade la URL pública como servidor MCP remoto en Configuración > Conectores (por ejemplo, https://mcp.example.com/mcp). Claude Desktop maneja el flujo OAuth automáticamente.

staticClients:
  - id: argo-cd-cli
    name: Argo CD CLI
    public: true
    redirectURIs:
      - http://localhost
      - http://localhost:8085/auth/callback
      - http://localhost:9382/callback
      - https://claude.ai/api/mcp/auth_callback

OAuth mediante un proveedor OIDC externo (sin Dex)

Para instancias de ArgoCD configuradas con oidc.config en lugar de dex.config: ArgoCD se comunica directamente con el proveedor de identidad y no ejecuta Dex, por lo que /api/dex/* no responde nada y AUTH_MODE=oauth no puede completar un flujo. AUTH_MODE=oidc actúa como proxy hacia ese mismo proveedor, y el RBAC por usuario funciona exactamente igual que en el modo Dex.

Los dos ajustes son mutuamente excluyentes en ArgoCD (oidc.config gana y Dex nunca se sirve), así que elige el modo que coincida con tu instancia:

docker run -p 8080:8080 \
  -e ARGOCD_BASE_URL=https://argocd.example.com \
  -e MCP_TRANSPORT=http \
  -e AUTH_MODE=oidc \
  -e SERVER_BASE_URL=http://localhost:8080 \
  ghcr.io/matthisholleville/argocd-mcp:latest

No se necesita emisor ni ID de cliente: el servidor lee el propio /api/v1/settings de ArgoCD al iniciar y utiliza el proveedor que declara, prefiriendo cliClientID sobre clientID cuando ambos están configurados. Anula con OIDC_ISSUER + OIDC_CLIENT_ID (ambos juntos) para apuntar a otra cosa. La conexión del cliente es idéntica al modo Dex.

{SERVER_BASE_URL}/oauth/callback

-e OIDC_REQUESTED_ID_TOKEN_CLAIMS='{"id_token":{"groups":{"essential":true}}}'

Búsqueda Semántica (opcional)

Habilita la búsqueda vectorial impulsada por Ollama para mejores resultados en consultas de lenguaje natural:

docker compose up --build -d  # Starts Ollama + argocd-mcp with embeddings

Configura EMBEDDINGS_ENABLED=true, OLLAMA_URL y EMBEDDINGS_MODEL (por defecto nomic-embed-text).

Modo de Solo Lectura (opcional)

Configura DISABLE_WRITE=true para evitar cualquier acción disruptiva en tu clúster. Cuando está habilitado:

• Los endpoints de escritura están ocultos — las operaciones POST, PUT, PATCH, DELETE se filtran del índice de búsqueda, por lo que el LLM nunca las descubre.
• La ejecución de escritura está bloqueada — incluso si un llamador elabora manualmente una solicitud execute_operation con un método de escritura, es rechazada.
• Las operaciones de lectura funcionan normalmente — GET, HEAD, OPTIONS no se ven afectadas.

Esto es ideal para entornos de producción, demostraciones o cualquier configuración donde quieras que los LLM observen pero nunca modifiquen tus recursos de ArgoCD.

# Claude Code
claude mcp add argocd -s user -- \
  docker run --rm -i \
  -e ARGOCD_BASE_URL=https://argocd.example.com \
  -e ARGOCD_TOKEN=your-token \
  -e DISABLE_WRITE=true \
  ghcr.io/matthisholleville/argocd-mcp:latest

Alcance de Recursos (opcional)

Establece ALLOWED_RESOURCES para restringir qué tipos de recursos de ArgoCD puede descubrir y llamar el LLM. Esto filtra tanto los resultados de búsqueda como bloquea la ejecución de endpoints fuera de alcance.

# Only expose application and version endpoints
ALLOWED_RESOURCES=ApplicationService,VersionService

Se combina con DISABLE_WRITE:

# Read-only access to applications only
DISABLE_WRITE=true
ALLOWED_RESOURCES=ApplicationService

Etiquetas de recursos disponibles (de la especificación OpenAPI de ArgoCD):

La coincidencia no distingue entre mayúsculas y minúsculas (applicationservice funciona).

Modo de Herramientas Generadas (opcional)

Establece TOOL_MODE=generated para crear una herramienta MCP por endpoint de ArgoCD al inicio. En lugar de buscar y luego ejecutar, el LLM llama directamente a herramientas tipadas:

# Claude Code
claude mcp add argocd -s user -- \
  docker run --rm -i \
  -e ARGOCD_BASE_URL=https://argocd.example.com \
  -e ARGOCD_TOKEN=your-token \
  -e TOOL_MODE=generated \
  ghcr.io/matthisholleville/argocd-mcp:latest

argocd_application_sync(
  name:      "frontend"      ← path param (required)
  revision:  "HEAD"          ← body param, flattened
  dryRun:    true            ← body param, flattened
  strategy:  '{"apply":{}}'  ← nested object stays JSON string
)

Límite de Tasa (opcional)

Protege ArgoCD de llamadas API excesivas estableciendo RATE_LIMIT. Solo execute_operation tiene límite de tasa — la búsqueda es local y no se ve afectada.

RATE_LIMIT=10              # 10 requests/sec per user
RATE_LIMIT_BURST=20        # allow short bursts up to 20

Plantillas de Prompts

Flujos de trabajo preempaquetados para operaciones comunes de ArgoCD. Los clientes MCP (Claude Desktop, Cursor) muestran estos como prompts seleccionables en su interfaz.

Cada prompt guía al LLM a través de un flujo de trabajo paso a paso usando search_operations y execute_operation. No se necesitan herramientas adicionales.

Registro de Auditoría

El registro de auditoría está habilitado por defecto. Cada llamada search_operations y execute_operation emite una entrada de registro JSON estructurada a stderr:

{"time":"2026-03-22T10:00:00Z","level":"INFO","msg":"audit","tool":"execute_operation","method":"GET","path":"/api/v1/applications","blocked":false,"duration_ms":142,"status_code":200,"user":"alice@example.com"}

Cada entrada incluye:

• tool — search_operations o execute_operation
• user — correo del token OAuth (vacío en modo de token estático)
• method / path — la llamada API de ArgoCD (ejecución) o query (búsqueda)
• status_code — código de respuesta HTTP ascendente
• blocked — true si la llamada fue rechazada por DISABLE_WRITE o ALLOWED_RESOURCES
• duration_ms — tiempo de ida y vuelta en milisegundos
• error — mensaje de error (registrado a nivel ERROR cuando está presente)

Establece AUDIT_LOG=false para deshabilitar.

Métricas

Las métricas de Prometheus se exponen en GET /metrics siempre que MCP_TRANSPORT=http (no hay superficie HTTP en modo stdio, por lo que no hay nada que raspar allí). A diferencia del registro de auditoría, las métricas están siempre activas y no se pueden deshabilitar: no llevan identidad de usuario, solo un conjunto de etiquetas tool/status acotado, por lo que no hay razón de volumen o privacidad para apagarlas.

tool es search_operations / execute_operation en el modo de búsqueda predeterminado, o el nombre de herramienta generado (p. ej., argocd_application_sync) en TOOL_MODE=generated.

curl http://localhost:8080/metrics | grep mcp_tool_

# Call rate by tool, last 5 minutes
sum by (tool) (rate(mcp_tool_calls_total[5m]))

# p95 latency
histogram_quantile(0.95, sum by (le, tool) (rate(mcp_tool_duration_seconds_bucket[5m])))

# Error ratio
sum(rate(mcp_tool_calls_total{status="error"}[5m])) / sum(rate(mcp_tool_calls_total[5m]))

Configuración

Compilar desde el código fuente

make build
ARGOCD_BASE_URL=https://argocd.example.com ARGOCD_TOKEN=xxx ./bin/argocd-mcp

Licencia

MIT