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

Por que usar

Principais recursos

Listar/inspecionar aplicações ArgoCD entre projetos
Mostrar status de sincronização, saúde e informações da última sincronização
Comparar estado de cluster ativo vs estado git desejado
Disparar sincronização (com opções de prune/force) quando autorizado
Ler manifestos da aplicação sem acesso cluster kubectl

Demo ao vivo

Como fica na prática

argocd.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

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

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

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

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

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

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

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

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

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

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

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

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

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

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: ArgoCD

Encontrar aplicações ArgoCD que saíram de sincronização

👤 Equipes de Plataforma / SRE executando GitOps ⏱ ~20 min intermediate

Quando usar: Semanalmente: quais aplicações em quais clusters estão OutOfSync ou Degraded e por quê?

Pré-requisitos

Token da API ArgoCD com escopo de leitura — argocd account generate-token --account <read-only-user>
URL do servidor ArgoCD — ARGOCD_SERVER=argocd.my.company.com

Fluxo

Listar aplicações com status

Liste todas as aplicações ArgoCD. Para cada uma: nome, projeto, status de sincronização, status de saúde, hora da última sincronização.✓ Copiado

→ Inventário completo
Focar em desincronização

Filtre para aplicações com syncStatus != 'Synced' ou health != 'Healthy'. Classifique por tempo desde a última sincronização.✓ Copiado

→ Lista de aplicações com problemas
Comparar uma aplicação específica

Para a aplicação <name>, mostre a diferença entre desejado (git) e ativo. Quais recursos estão fora de sincronização?✓ Copiado

→ Diferença no nível de recursos

Resultado: Um relatório de desincronização semanal identificando quais aplicações precisam de atenção e por quê.

Armadilhas

Desincronização causada por um recurso legítimo somente em tempo de execução (por ex., réplicas escaladas por HPA) — Configure ignoreDifferences na especificação da Aplicação para excluir campos que mudam em tempo de execução

Combine com: notion

Revisar e aplicar uma sincronização para uma aplicação específica

👤 Engenheiros de DevOps promovendo mudanças ⏱ ~15 min intermediate

Quando usar: Um PR foi mesclado para main; ArgoCD mostra a aplicação como OutOfSync pendendo sua aprovação.

Pré-requisitos

Token com permissão de sincronização no projeto de destino — Role with applications, sync, <project>/* allowed

Fluxo

Inspecionar a mudança pendente

Para a aplicação <name>, mostre a diferença. Quais recursos mudam, qual é o raio de impacto?✓ Copiado

→ Diferença concreta
Verificar o commit de origem

Para qual SHA de commit o estado desejado aponta? Mostre a mensagem de commit do GitHub e o PR.✓ Copiado

→ Contexto de Commit + PR
Sincronizar com prune=false primeiro

Dispare sincronização para <name> com prune=false, dryRun=false. Aguarde conclusão, mostre status final.✓ Copiado

→ Sync Succeeded; health Healthy

Resultado: Um deploy com revisão prévia, não uma surpresa; exclusão por prune ocorre apenas explicitamente.

Armadilhas

Sincronização com prune=true pode excluir recursos que você ainda precisa — Sempre comece com prune=false; habilite prune apenas quando você confirmar que não existem recursos criados manualmente no namespace

Combine com: github

Reversão de emergência para uma revisão git anterior

👤 SREs durante um incidente de deploy ruim ⏱ ~15 min advanced

Quando usar: Um deploy saiu, erros aumentaram e você precisa reverter para o último estado conhecido como bom.

Fluxo

Obter histórico atual +

Para a aplicação <name>, mostre a revisão atual e as últimas 5 revisões implantadas com timestamps.✓ Copiado

→ Tabela de histórico
Escolher o alvo de reversão

Qual era a revisão 2 sincronizações atrás? Confirme que seu SHA corresponde ao commit git antes do incidente começar.✓ Copiado

→ SHA de destino identificado
Reverter

Sincronize <name> para revisão <SHA> com prune=false. Monitore até Healthy. Poste no Teams quando concluído.✓ Copiado

→ Aplicação revertida + notificação enviada

Resultado: Uma reversão limpa com trilha de auditoria, normalmente em menos de 5 minutos.

Armadilhas

Reverter apenas a aplicação, mas a migração de BD já foi executada — Migrações de BD precisam de seu próprio plano de reversão; às vezes 'avançar' com uma correção é mais seguro do que reverter código em relação a um esquema modificado

Combine com: sentry · ms-teams

Construir um inventário de aplicações entre clusters

👤 Equipes de plataforma gerenciando muitos clusters ⏱ ~20 min intermediate

Quando usar: Você executa ArgoCD em um modelo hub-spoke e deseja uma lista simples: 'quais aplicações são executadas onde'.

Fluxo

Listar clusters que ArgoCD gerencia

Liste todos os clusters registrados em ArgoCD com seu nome e URL do servidor.✓ Copiado

→ Inventário de clusters
Mapear aplicações para clusters

Para cada aplicação, mostre seu cluster de destino e namespace. Agrupe por cluster.✓ Copiado

→ Lista de aplicações por cluster
Sinalizar colocações incomuns

Alguma aplicação implantada em um cluster inesperado (por ex., aplicação 'somente-prod' em um cluster dev)? Sinalize com motivo.✓ Copiado

→ Lista de anomalias

Resultado: Um mapa atualizado do que é executado onde, útil para auditorias e planejamento de capacidade.

Armadilhas

Entradas de cluster obsoletas — segredos removidos, mas cluster ainda listado — Verifique periodicamente se cada cluster está acessível; remova os obsoletos

Combinações

Combine com outros MCPs para 10× de alavancagem

argocd + github

Referenciar cruzadamente sincronização Argo com o PR que a causou

Para a aplicação <name>, mostre o SHA de revisão atual; busque o PR do GitHub que o introduziu e resuma a mudança.✓ Copiado

argocd + sentry

Correlacionar uma sincronização Argo com um pico de erro pós-implantação

Aplicação <name> foi sincronizada às 14:02; erros do Sentry aumentaram depois disso? Se sim, mostre o principal problema introduzido.✓ Copiado

argocd + ms-teams

Postar eventos de sincronização/reversão em um canal do Teams

Após qualquer sincronização manual da aplicação <name>, poste uma mensagem no Teams #deploys com o SHA de revisão e quem a disparou.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
list_applications	project?, selector?	Inventário de aplicações	free
get_application	name	Estado detalhado de uma aplicação específica	free
get_application_diff	name, revision?	Visualizar o que uma sincronização alteraria	free
sync_application	name, revision?, prune?, dryRun?, resources?	Aplicar mudanças pendentes	free (triggers cluster work)
get_application_resource_tree	name	Inspecionar os recursos ativos que uma aplicação possui	free
list_clusters		Inventário entre clusters	free

Custo e limites

O que custa rodar

Cota de API: Limitado pela capacidade do seu servidor ArgoCD; limite prático ~10 req/s
Tokens por chamada: Lista de aplicações: 500–3000 tokens. Diff: até 5000.
Monetário: Gratuito — ArgoCD é open source, você apenas paga pela infraestrutura que o hospeda.
Dica: Armazene em cache a lista de aplicações; use seletores (projeto, label) para restringir consultas em vez de listar tudo.

Segurança

Permissões, segredos, alcance

Escopos mínimos: leitura em aplicações, clusters para sessões somente-leitura

Armazenamento de credenciais: ARGOCD_AUTH_TOKEN e ARGOCD_SERVER em env

Saída de dados: Chamadas apenas para seu servidor ArgoCD

Nunca conceda: admin sincronização em todos os projetos sem motivo account:update

Permissão de sincronização pode implantar manifestos arbitrários — trate como acesso de escrita em produção.
Use políticas RBAC com escopo de projeto em vez de cluster-admin para contas de automação.

Solução de problemas

Erros comuns e correções

401 Não autenticado

ARGOCD_AUTH_TOKEN expirado ou revogado. Regenere via argocd account generate-token.

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

403 Permissão negada na sincronização

Função carece de permissão applications, sync, <project>/*. Atualize AppProject ou função da conta.

Sincronização presa em Progressing por >10 min

Geralmente um recurso preso — verifique resource-tree para um hook falhando ou um controlador preso; pode precisar de intervenção manual no cluster.

Diff mostra desincronização inesperada a cada sincronização

Controladores mutando campos em tempo de execução. Adicione ignoreDifferences à especificação da Aplicação para esses campos.

Alternativas

ArgoCD vs. outros

Alternativa	Quando usar	Troca
Flux MCP	Você usa Flux em vez de ArgoCD para GitOps	Engine GitOps diferente; modelo CLI-primeiro
Kubernetes MCP (raw kubectl)	Você quer acesso direto ao cluster sem abstração GitOps	Imperativo — derrota o propósito de GitOps para aplicações gerenciadas

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills