ArgoCD

argocd-mcp

Toda a API do ArgoCD, exposta a LLMs via MCP.
103+ endpoints. Zero handlers codificados. Dois modos: busca ou ferramentas geradas.

Início Rápido • Como Funciona • OAuth • OIDC • Configuração

A maioria dos servidores MCP do ArgoCD codifica algumas operações: listar aplicações, sincronizar, obter status. Quando o ArgoCD adiciona um novo recurso, você espera o mantenedor adicioná-lo.

argocd-mcp adota uma abordagem diferente, inspirada no servidor MCP da Cloudflare, que cobre 2500+ endpoints com apenas 2 ferramentas. Ele lê a especificação OpenAPI do ArgoCD na inicialização e expõe cada endpoint por meio de apenas 2 ferramentas: search e execute. Nova versão do ArgoCD? Reinicie o servidor. Pronto.

• 103+ endpoints da especificação OpenAPI do ArgoCD, zero handlers codificados
• Dois modos de ferramenta: search (2 meta-ferramentas) ou generated (1 ferramenta tipada por endpoint)
• Funciona com Claude Desktop, Claude Code, Cursor ou qualquer cliente MCP
• Sem código por endpoint — a especificação OpenAPI é a fonte da verdade
• Três modos de autenticação: token estático, OAuth via ArgoCD Dex, ou OAuth via provedor OIDC externo que o ArgoCD confia (ambos fornecem RBAC por usuário)
• Modo somente leitura — desative todas as operações de escrita com uma única flag
• Escopo de recursos — restrinja quais recursos do ArgoCD são expostos com ALLOWED_RESOURCES
• Limitação de taxa — token bucket por usuário para proteger o ArgoCD de chamadas excessivas
• Modelos de prompt — fluxos de trabalho pré-empacotados para operações comuns (aplicações não saudáveis, diff, rollback, logs)
• Registro de auditoria — logs JSON estruturados para cada chamada de ferramenta (usuário, método, caminho, status, duração)
• Anotações MCP — ferramentas anotadas como somente leitura, destrutivas ou idempotentes para categorização adequada no cliente
• Busca semântica opcional via embeddings Ollama

Como Funciona

Na inicialização, o servidor busca a especificação Swagger do ArgoCD e analisa cada endpoint. Em seguida, expõe-os a LLMs por meio de um dos dois modos:

Modo de busca (padrão, TOOL_MODE=search)

Duas meta-ferramentas lidam com todos os 103+ endpoints. O LLM descobre endpoints pesquisando e depois os chama por meio de um executor 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 gerado (TOOL_MODE=generated)

Uma ferramenta MCP tipada por endpoint, gerada dinamicamente na inicialização. O LLM chama argocd_application_sync(name, revision) diretamente — sem etapa de busca, sem construção de caminho.

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]

Qual modo escolher?

Clientes como Claude Code e Claude Desktop suportam carregamento adiado de ferramentas — eles só carregam definições de ferramentas no contexto quando necessário, então as 103+ ferramentas não consomem a janela de contexto antecipadamente.

Início Rápido

Helm Chart (Kubernetes)

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

Veja todas as opções de configuração em charts/argocd-mcp/values.yaml.

Token Estático (simples)

Melhor para desenvolvimento local, CI/CD ou configurações de usuário único. Usa um token de API estático do 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

Adicione ao seu config MCP do 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 via ArgoCD Dex (RBAC por usuário)

Melhor para configurações multiusuário e produção. Cada usuário autentica com sua própria identidade via Dex integrado do ArgoCD. Nenhum token estático necessário — o id_token do Dex do usuário é encaminhado ao ArgoCD, que aplica suas políticas RBAC por usuário.

Passo 1: Inicie o 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

Passo 2: Conecte seu cliente MCP

Claude Code

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

Em seguida, execute /mcp dentro do Claude Code para autenticar via navegador.

Claude Desktop

O Claude Desktop requer uma URL publicamente acessível (o redirecionamento OAuth passa por claude.ai). Exponha o servidor via proxy reverso ou ngrok e defina SERVER_BASE_URL de acordo. No modo oidc, esse callback não é uma URL de loopback, então também precisa estar na lista de permissões: OIDC_ALLOWED_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback.

Adicione a URL pública como um servidor MCP remoto em Configurações > Conectores (ex.: https://mcp.example.com/mcp). O Claude Desktop lida com o fluxo OAuth automaticamente.

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 via provedor OIDC externo (sem Dex)

Para instâncias do ArgoCD configuradas com oidc.config em vez de dex.config: o ArgoCD fala diretamente com o provedor de identidade e não executa Dex, então /api/dex/* não responde nada e AUTH_MODE=oauth não consegue completar um fluxo. AUTH_MODE=oidc faz proxy para esse mesmo provedor, e o RBAC por usuário funciona exatamente como no modo Dex.

As duas configurações são mutuamente exclusivas no ArgoCD (oidc.config vence e o Dex nunca é servido), então escolha o modo que corresponde à sua instância:

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

Nenhum issuer ou client id é necessário: o servidor lê o próprio /api/v1/settings do ArgoCD na inicialização e usa o provedor que ele declara, preferindo cliClientID sobre clientID quando ambos estão definidos. Substitua com OIDC_ISSUER + OIDC_CLIENT_ID (ambos juntos) para apontar para outra coisa. A conexão do cliente é idêntica ao modo Dex.

{SERVER_BASE_URL}/oauth/callback

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

Busca Semântica (opcional)

Ative a busca vetorial com Ollama para melhores resultados em consultas de linguagem natural:

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

Defina EMBEDDINGS_ENABLED=true, OLLAMA_URL e EMBEDDINGS_MODEL (padrão para nomic-embed-text).

Modo Somente Leitura (opcional)

Defina DISABLE_WRITE=true para impedir qualquer ação disruptiva no seu cluster. Quando ativado:

• Os endpoints de escrita estão ocultos — as operações POST, PUT, PATCH, DELETE são filtradas do índice de busca, para que o LLM nunca as descubra.
• A execução de escrita é bloqueada — mesmo que um chamador monte manualmente uma requisição execute_operation com um método de escrita, ela é rejeitada.
• As operações de leitura funcionam normalmente — GET, HEAD, OPTIONS não são afetadas.

Isso é ideal para ambientes de produção, demonstrações ou qualquer configuração em que você queira que LLMs observem, mas nunca modifiquem, seus recursos do 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

Escopo de Recursos (opcional)

Defina ALLOWED_RESOURCES para restringir quais tipos de recursos do ArgoCD o LLM pode descobrir e chamar. Isso filtra tanto os resultados da busca quanto bloqueia a execução de endpoints fora do escopo.

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

Combina com DISABLE_WRITE:

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

Tags de recursos disponíveis (a partir da especificação OpenAPI do ArgoCD):

A correspondência não diferencia maiúsculas de minúsculas (applicationservice funciona).

Modo de Ferramentas Geradas (opcional)

Defina TOOL_MODE=generated para criar uma ferramenta MCP por endpoint do ArgoCD na inicialização. Em vez de buscar e depois executar, o LLM chama diretamente ferramentas 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
)

Limitação de Taxa (opcional)

Proteja o ArgoCD de chamadas de API excessivas definindo RATE_LIMIT. Apenas execute_operation é limitado por taxa — a busca é local e não é afetada.

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

Modelos de Prompt

Fluxos de trabalho pré-empacotados para operações comuns do ArgoCD. Clientes MCP (Claude Desktop, Cursor) mostram esses prompts como selecionáveis em sua interface.

Cada prompt guia o LLM por um fluxo de trabalho passo a passo usando search_operations e execute_operation. Nenhuma ferramenta adicional é necessária.

Log de Auditoria

O log de auditoria está habilitado por padrão. Cada chamada search_operations e execute_operation emite uma entrada de log JSON estruturada para o 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 inclui:

• tool — search_operations ou execute_operation
• user — email do token OAuth (vazio no modo de token estático)
• method / path — a chamada de API do ArgoCD (execute) ou query (search)
• status_code — código de resposta HTTP upstream
• blocked — true se a chamada foi rejeitada por DISABLE_WRITE ou ALLOWED_RESOURCES
• duration_ms — tempo de ida e volta em milissegundos
• error — mensagem de erro (registrada no nível ERROR quando presente)

Defina AUDIT_LOG=false para desabilitar.

Métricas

As métricas do Prometheus são expostas em GET /metrics sempre que MCP_TRANSPORT=http (não há superfície HTTP no modo stdio, então nada para coletar lá). Ao contrário do log de auditoria, as métricas estão sempre ativas e não podem ser desabilitadas: elas não carregam identidade de usuário, apenas um conjunto de rótulos limitado tool/status, então não há motivo de volume ou privacidade para desativá-las.

tool é search_operations / execute_operation no modo de busca padrão, ou o nome da ferramenta gerada (ex., argocd_application_sync) em 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]))

Configuração

Compilar a partir do código-fonte

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

Licença

MIT