Argo CD

Interaja com aplicações do Argo CD através de linguagem natural.

Documentação

Servidor MCP do Argo CD

Uma implementação de servidor Model Context Protocol (MCP) para Argo CD, permitindo que assistentes de IA interajam com seus aplicativos Argo CD por meio de linguagem natural. Este servidor permite integração perfeita com o Visual Studio Code e outros clientes MCP por meio dos protocolos de transporte stdio e HTTP stream.

argocd-mcp-demo

Recursos

Protocolos de Transporte: Suporta modos de transporte stdio e HTTP stream para integração flexível com diferentes clientes
Integração Completa com a API do Argo CD: Fornece acesso abrangente aos recursos e operações do Argo CD
Pronto para Assistentes de IA: Ferramentas pré-configuradas para assistentes de IA interagirem com o Argo CD em linguagem natural

Ferramentas Disponíveis

O servidor fornece as seguintes ferramentas de gerenciamento do ArgoCD:

Gerenciamento de Clusters

list_clusters: Listar todos os clusters registrados no ArgoCD

Gerenciamento de Projetos

get_appproject: Obter informações detalhadas sobre um AppProject (projeto) específico

Gerenciamento de Aplicações

list_applications: Listar e filtrar todas as aplicações
get_application: Obter informações detalhadas sobre uma aplicação específica
create_application: Criar uma nova aplicação
update_application: Atualizar uma aplicação existente
delete_application: Excluir uma aplicação
sync_application: Acionar uma operação de sincronização em uma aplicação

Gerenciamento de Recursos

get_application_resource_tree: Obter a árvore de recursos de uma aplicação específica
get_application_managed_resources: Obter recursos gerenciados de uma aplicação específica
get_application_workload_logs: Obter logs para workloads da aplicação (Pods, Deployments, etc.)
get_resource_events: Obter eventos para recursos gerenciados por uma aplicação
get_resource_actions: Obter ações disponíveis para recursos
run_resource_action: Executar uma ação em um recurso

Instalação

Pré-requisitos

Node.js (v18 ou superior recomendado)
Gerenciador de pacotes pnpm (para desenvolvimento)
Instância do Argo CD com acesso à API
Token da API do Argo CD (veja a documentação para instruções)

Uso com o Cursor

Siga a documentação do Cursor para suporte a MCP e crie um arquivo .cursor/mcp.json no seu projeto:

{
  "mcpServers": {
    "argocd-mcp": {
      "command": "npx",
      "args": [
        "argocd-mcp@latest",
        "stdio"
      ],
      "env": {
        "ARGOCD_BASE_URL": "<argocd_url>",
        "ARGOCD_API_TOKEN": "<argocd_token>"
      }
    }
  }
}

Inicie uma conversa com o modo Agent para usar o MCP.

Uso com o VSCode

Siga a documentação de uso de servidores MCP no VS Code e crie um arquivo .vscode/mcp.json no seu projeto:

{
  "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 uma conversa com um assistente de IA no VS Code que suporte MCP.

Uso com o Claude Desktop

Siga a documentação de MCP no Claude Desktop e crie um arquivo de configuração 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 o Claude Desktop para usar este arquivo de configuração nas configurações.

Certificados Autoassinados

Se sua instância do Argo CD usa certificados autoassinados ou certificados de uma Autoridade Certificadora (CA) privada, talvez seja necessário adicionar a seguinte variável de ambiente à sua configuração:

"NODE_TLS_REJECT_UNAUTHORIZED": "0"

Isso desativa a validação de certificados TLS para Node.js ao conectar a instâncias do Argo CD que usam certificados autoassinados ou certificados de CAs privadas que não são confiáveis no armazenamento de certificados do seu sistema.

Aviso: Desativar a verificação SSL reduz a segurança. Use esta configuração apenas em ambientes de desenvolvimento ou quando você entender as implicações de segurança.

Fornecendo Credenciais do ArgoCD

O servidor se conecta ao ArgoCD usando uma URL base e um token de API.

Token de API — somente header / variável de ambiente (obrigatório)

O token de API do ArgoCD é um segredo e é lido apenas na camada de transporte, nunca a partir de um argumento de chamada de ferramenta:

Headers HTTP (somente transporte HTTP): x-argocd-api-token.
Variáveis de ambiente: ARGOCD_API_TOKEN (todos os transportes).

Este token é somente de saída: ele autentica este servidor no ArgoCD e nunca autoriza um chamador de entrada. Veja Exposição de Rede para saber quem pode alcançar o listener.

Este é o token padrão. Ele é obrigatório, a menos que um registro de tokens esteja configurado: no transporte HTTP, uma conexão que não fornece token (nem header nem variável de ambiente) é rejeitada com 400 Bad Request, mas quando um registro está configurado, uma conexão sem token é permitida porque cada chamada resolve seu próprio token de registro. Manter o token fora dos argumentos das ferramentas garante que ele nunca entre em prompts, contexto do modelo ou logs de chamadas de ferramentas.

URL base — header / variável de ambiente, ou argumento por chamada

A URL base pode ser fornecida no nível da sessão (resolvida uma vez quando o servidor inicia ou quando um cliente HTTP se conecta):

Headers HTTP (somente transporte HTTP): x-argocd-base-url.
Variáveis de ambiente: ARGOCD_BASE_URL (todos os transportes).

Além disso, toda ferramenta aceita um argumento opcional argocdBaseUrl:

Se uma URL base padrão de sessão existir, argocdBaseUrl é opcional e substitui o padrão para aquela chamada específica.
Se nenhuma URL base padrão de sessão estiver configurada (header e variável de ambiente ausentes), argocdBaseUrl é obrigatório; uma chamada sem ele retorna um erro.

Registro de tokens — tokens por URL base (multi-instância)

Para direcionar múltiplas instâncias do ArgoCD, cada uma com seu próprio token, configure um registro de tokens. Como os tokens são segredos, o registro é lido de um arquivo JSON, não de uma variável de ambiente — aponte ARGOCD_TOKEN_REGISTRY_PATH para o arquivo (por exemplo, um secret Kubernetes montado). Isso mantém os tokens fora do ambiente do processo, dumps de falha e herança de processos filhos.

ARGOCD_TOKEN_REGISTRY_PATH=/app/argocd-mcp/token-registry.json

O arquivo contém um array JSON que mapeia uma URL base para o token que deve ser usado para ela:

[
  { "baseUrl": "https://argo-a.example.com", "token": "<token-a>" },
  { "baseUrl": "https://argo-b.example.com", "token": "<token-b>" }
]

Proteja o arquivo. Restrinja-o ao usuário do servidor (por exemplo, chmod 400) e prefira um mecanismo de gerenciamento de segredos (volume de secret Kubernetes, agente Vault, etc.) em vez de um arquivo de texto simples no disco.

Desenvolvimento local. Os alvos make run / make dev são executados sem registro por padrão; passe ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json para usar um. Não coloque o arquivo em dist/ — tsup é executado com clean: true e limpa esse diretório a cada build. Veja Executando localmente.

Com um registro configurado, um chamador direciona uma instância passando apenas o argumento (não secreto) argocdBaseUrl; o servidor o associa ao token registrado. O token nunca aparece no payload da chamada de ferramenta.

Dois tipos de token

O servidor resolve chamadas usando um de dois tokens distintos. Mantê-los separados é o que faz o modelo de segurança funcionar:

	Token padrão	Token de registro
Origem	header `x-argocd-api-token` / variável de ambiente `ARGOCD_API_TOKEN` (a credencial da sessão)	Uma entrada `token` no arquivo JSON `ARGOCD_TOKEN_REGISTRY_PATH`, chaveada por `baseUrl`
Escopo	Somente a URL base padrão (`x-argocd-base-url` / `ARGOCD_BASE_URL`)	A URL base específica à qual sua entrada está chaveada
Usado para	Uma chamada que direciona a URL base padrão	Uma chamada que direciona qualquer URL base presente no registro (incluindo a padrão, como fallback)
Nunca usado para	Qualquer URL base diferente da padrão — ele nunca é enviado a um host diferente	Qualquer URL base não registrada

A regra cardinal: o token padrão está vinculado à URL base padrão; o token de qualquer outro host deve vir do registro. Um token de registro está vinculado exatamente ao host sob o qual está registrado.

Ordem de resolução

Para uma determinada chamada, a URL base resolvida é o argumento argocdBaseUrl se fornecido; caso contrário, o padrão da sessão. O token é então escolhido por:

A chamada direciona a URL base padrão → use o token padrão. Se nenhum token padrão foi fornecido (uma sessão sem token), recorra ao token de registro para essa URL base, se existir.
A chamada direciona qualquer outra URL base → use o token de registro apenas para essa URL base. O token padrão nunca é usado aqui — ele não é enviado a um host diferente do padrão.
Se nenhum dos casos se aplicar (nenhum token pode ser resolvido para a URL base solicitada), a chamada retorna um erro "Missing required ArgoCD API token" e nenhuma requisição é feita a esse host.

Por que o token padrão está vinculado à URL base padrão. O argumento argocdBaseUrl vem da chamada da ferramenta, então um chamador (ou um modelo com injeção de prompt) poderia apontá-lo para um host arbitrário. Se o token padrão fosse associado a qualquer URL base fornecida, esse token seria enviado — como um header Authorization: Bearer — para o host do atacante. Restringir o token padrão à URL base padrão e exigir uma entrada explícita no registro para qualquer outro host evita essa exfiltração de token. Para direcionar instâncias adicionais, você deve registrar seus tokens (e, portanto, seus hostnames) antecipadamente.

As URLs base são normalizadas para busca (host em minúsculas, barras finais ignoradas), então pequenas diferenças de formatação ainda correspondem. Quando um registro está configurado, o transporte HTTP não exige mais x-argocd-api-token no momento da conexão — uma conexão sem token é permitida porque a URL base por chamada resolve seu próprio token. Se ARGOCD_TOKEN_REGISTRY_PATH estiver definido, mas o arquivo estiver ausente, ilegível ou malformado, o servidor falha de forma segura: ele lança um erro na inicialização em vez de silenciosamente recorrer à sua credencial padrão, para que um registro mal configurado nunca cause chamadas roteadas com o token errado.

Por exemplo, uma requisição tools/call substituindo apenas a URL base:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_applications",
    "arguments": {
      "argocdBaseUrl": "https://argocd.other-cluster.example.com"
    }
  }
}

Substituir a URL base para uma instância diferente exige um token de registro. O token padrão (x-argocd-api-token / ARGOCD_API_TOKEN) está vinculado somente à URL base padrão e nunca é enviado a um host diferente. Substituir argocdBaseUrl para apontar para a instância padrão (mesmo host, formatação à parte) reutiliza o token padrão; apontá-lo para qualquer outra instância exige um token de registro para essa instância; caso contrário, a chamada falha com "Missing required ArgoCD API token" e nenhuma requisição é enviada. Isso é intencional — veja por que o token padrão está vinculado à URL base padrão acima.

Exposição de Rede

Os transportes http e sse abrem um listener de rede que alcança todas as ferramentas do ArgoCD, incluindo create_application, delete_application, sync_application e run_resource_action. Por padrão, ele vincula apenas ao loopback.

ARGOCD_API_TOKEN não o protege. Esse token autentica este servidor no ArgoCD. Ele não diz nada sobre quem é o chamador. O acesso de entrada é controlado pelas configurações abaixo.

Configuração	Flag	Variável de ambiente	Padrão	O que faz
Endereço de bind	`--bind-address`	`MCP_BIND_ADDRESS`	`127.0.0.1`	Em qual endereço o listener aceita conexões.
Token de entrada	—	`MCP_AUTH_TOKEN`	não definido	Quando definido, toda requisição deve conter `Authorization: Bearer <token>`.
`Host` permitidos	`--allowed-host-header`	—	nomes de loopback	Hostname extra aceito no header `Host` de uma requisição. Repita por nome.
`Origin` permitidos	`--allowed-origin`	—	origens de loopback	Origem de navegador extra aceita no header `Origin` de uma requisição. Repita por origem.
Autenticação externa	`--allow-unauthenticated`	—	`false`	Permite um bind não-loopback sem token, quando algo na frente já autentica os chamadores.
Porta	`--port`	—	`3000`	Em qual porta escutar.

--bind-address decide quem pode se conectar. --allowed-host-header apenas verifica o que um cliente já conectado afirma. Eles não são um par, e o segundo não é um firewall.

Flags sem variável de ambiente são passadas como argumentos, também em um contêiner: docker run <image> http --allow-unauthenticated.

Comportamento:

Ampliar o bind exige MCP_AUTH_TOKEN ou --allow-unauthenticated. Caso contrário, o servidor registra o motivo e encerra com código diferente de zero, em vez de iniciar exposto.
Origin é sempre verificado, em esquema, host e porta. É isso que impede uma página web maliciosa, inclusive uma que use DNS rebinding.
Host é verificado em um bind de loopback, ou em qualquer bind com pelo menos um --allowed-host-header. Caso contrário, o hostname que os clientes usam legitimamente é desconhecido, então a verificação é ignorada e um aviso é registrado.
GET /healthz é isento, então uma sondagem do kubelet ainda funciona. Ela retorna apenas liveness.
Configuração inutilizável falha na inicialização com o motivo, em vez de ser ignorada.
Modo somente leitura é independente de tudo isso e limita o que qualquer chamador pode fazer.

Expondo o listener deliberadamente:

export MCP_AUTH_TOKEN=<inbound_token>
node dist/index.js http --bind-address 0.0.0.0 --allowed-host-header mcp.internal.example.com

A imagem do contêiner mantém o mesmo padrão de loopback, então não precisa de configuração extra quando o chamador compartilha seu namespace de rede, como um sidecar no mesmo pod Kubernetes:

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

Para publicar uma porta, amplie o bind e defina uma credencial de entrada:

docker run -p 3000:3000 \
  -e ARGOCD_BASE_URL=<argocd_url> -e ARGOCD_API_TOKEN=<argocd_token> \
  -e MCP_BIND_ADDRESS=0.0.0.0 -e MCP_AUTH_TOKEN=<inbound_token> \
  argoprojlabs/mcp-for-argocd

Quando o bind é ampliado e um proxy ou mesh já autentica os chamadores, use --allow-unauthenticated em vez de MCP_AUTH_TOKEN.

Consulte Notas do operador para as ressalvas de implantação.

Modo Somente Leitura

Se você quiser executar o MCP Server em modo somente leitura para evitar modificação de recursos ou aplicações, defina a variável de ambiente:

"MCP_READ_ONLY": "true"

Isso desabilitará as seguintes ferramentas:

create_application
update_application
delete_application
sync_application
run_resource_action

Por padrão, todas as ferramentas estarão disponíveis.

Modo Sem Estado

Por padrão, o transporte HTTP atribui um ID de sessão a cada conexão de cliente e mantém um mapa em memória das sessões ativas. Isso funciona bem para implantações de instância única, mas causa erros de 400 quando várias réplicas estão em execução sem sessões fixas, porque uma solicitação roteada para um pod diferente não encontrará a sessão criada no pod original.

Para executar sem requisitos de afinidade de sessão, inicie o servidor com a flag --stateless:

node dist/index.js http --stateless

Ou com Docker:

docker run -p 3000:3000 \
  -e ARGOCD_BASE_URL=<argocd_url> -e ARGOCD_API_TOKEN=<argocd_token> \
  -e MCP_BIND_ADDRESS=0.0.0.0 -e MCP_AUTH_TOKEN=<inbound_token> \
  argoprojlabs/mcp-for-argocd http --stateless

A imagem tem um ENTRYPOINT, então sobrescrever o comando substitui apenas os argumentos. Publicar uma porta é o que torna o bind mais amplo e o token de entrada necessários aqui; consulte Exposição de rede.

No modo sem estado:

Nenhum Mcp-Session-Id é retornado ou exigido — qualquer réplica pode lidar com qualquer solicitação
As credenciais do ArgoCD devem ser fornecidas em cada solicitação por meio de variáveis de ambiente ou cabeçalhos x-argocd-base-url / x-argocd-api-token (a URL base também pode ser sobrescrita por chamada via argumento da ferramenta argocdBaseUrl; o token da API é sempre apenas cabeçalho/ambiente)
GET /mcp e DELETE /mcp retornam 405 Method Not Allowed (SSE em nível de sessão e encerramento não são suportados)

Este modo é recomendado para implantações Kubernetes com Autoscaling Horizontal de Pods (HPA) onde sessões fixas em nível de rede não estão disponíveis.

Para Desenvolvimento

Clone o repositório:

git clone https://github.com/argoproj-labs/mcp-for-argocd.git
cd mcp-for-argocd

Instale as dependências do projeto:

pnpm install

Inicie o servidor de desenvolvimento com recarga automática habilitada:

pnpm run dev

Uma vez que o servidor esteja em execução, você pode utilizar o servidor MCP dentro do Visual Studio Code ou outro cliente MCP.

Executando localmente

O Makefile fornece alvos para executar o servidor sobre o transporte HTTP:

make run    # build, then run the HTTP server (production-style)
make dev    # run from source with hot reloading (tsx watch)

Por padrão, nenhum alvo define credenciais — o servidor inicia sem URL base ou token padrão, então os chamadores devem fornecê-los por solicitação (cabeçalhos x-argocd-base-url / x-argocd-api-token, ou o argumento da ferramenta argocdBaseUrl uma vez que um registro esteja configurado). Sobrescreva a porta da mesma forma:

make run PORT=4000

Para configurar credenciais, exporte a variável de ambiente relevante na linha de comando. Há três (todas opcionais):

Variável	Finalidade
`ARGOCD_BASE_URL`	URL padrão da instância ArgoCD usada quando uma chamada não a sobrescreve.
`ARGOCD_API_TOKEN`	Token de API estático para a URL base padrão.
`ARGOCD_TOKEN_REGISTRY_PATH`	Caminho para um registro de tokens JSON que mapeia URLs base para tokens (para direcionar várias instâncias).

Todas são credenciais de saída. Para quem pode alcançar o listener, consulte Exposição de rede.

# Single instance with a static base URL + token:
make run ARGOCD_BASE_URL=https://argo.example.com ARGOCD_API_TOKEN=<token>

# Multiple instances via a token registry:
make run ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json

# Both — a default instance plus extra instances resolved from the registry:
make dev ARGOCD_BASE_URL=https://argo.example.com ARGOCD_API_TOKEN=<token> \
  ARGOCD_TOKEN_REGISTRY_PATH=/path/to/tokens.json

Consulte Resolução de tokens para saber como o token padrão e o registro interagem. Se ARGOCD_TOKEN_REGISTRY_PATH estiver definido, mas o arquivo estiver ausente, ilegível ou malformado, o servidor falha de forma segura na inicialização.

Mantenha os tokens fora do histórico do seu shell. Passar ARGOCD_API_TOKEN=<token> diretamente na linha de comando do make registra o segredo no histórico do shell e o expõe na lista de processos. Prefira exportá-lo no shell primeiro para que nunca apareça na invocação do make:
export ARGOCD_API_TOKEN=<token>
make run ARGOCD_BASE_URL=https://argo.example.com
Um caminho de registro (ARGOCD_TOKEN_REGISTRY_PATH) e uma URL base não são segredos, então tudo bem passá-los inline.

Não coloque o arquivo de registro sob dist/ — builds do tsup com clean: true apagam esse diretório a cada build.

O servidor HTTP escuta em POST /mcp (127.0.0.1:3000 por padrão, consulte Exposição de rede para ampliar) com um endpoint de liveness GET /healthz. Para enviar uma solicitação, primeiro initialize uma sessão (capture o cabeçalho de resposta mcp-session-id), depois chame uma ferramenta, passando uma das URLs base registradas como o argumento argocdBaseUrl:

# 1. Initialize a session — note the mcp-session-id response header
curl -sD - http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

# 2. Call a tool, reusing that session id
curl -s http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'mcp-session-id: <session-id-from-step-1>' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_applications","arguments":{"argocdBaseUrl":"https://argo-a.example.com"}}}'

Para evitar gerenciar um ID de sessão, execute no modo sem estado (node dist/index.js http --stateless) para que cada POST /mcp seja autocontido.

Atualizando os Tipos do ArgoCD

Para atualizar as definições de tipos TypeScript com base na especificação mais recente da API do Argo CD:

Baixe o arquivo swagger.json da página de lançamentos do ArgoCD, por exemplo, aqui está o link do swagger.json para ArgoCD v2.14.11.
Coloque o arquivo swagger.json baixado no diretório raiz do projeto argocd-mcp.
Gere os tipos TypeScript a partir da definição Swagger executando o seguinte comando. Isso criará ou sobrescreverá o arquivo src/types/argocd.d.ts:
```
pnpm run generate-types
```
Atualize o arquivo src/types/argocd-types.ts para exportar os tipos necessários do src/types/argocd.d.ts recém-gerado. Esta etapa geralmente requer revisão manual para garantir que apenas os tipos necessários sejam expostos.

Créditos

O projeto foi inicialmente criado e doado por @jiachengxu, @imwithye, @hwwn e @alexmt da Akuity.