ArgoCD MCP Server

Gerencie aplicações e recursos do ArgoCD usando linguagem natural através de sua integração com API.

Documentação

ArgoCD MCP Server

Um servidor MCP (Model Context Protocol) que se integra à API do ArgoCD, permitindo que assistentes de IA e modelos de linguagem de grande porte gerenciem aplicações e recursos do ArgoCD por meio de interações em linguagem natural.

Recursos

Autenticação e Gerenciamento de Sessão:
- Recuperação de informações do usuário da API do ArgoCD
- Autenticação baseada em token com ArgoCD
- Acesso às configurações e definições do servidor
- Recuperação de informações de plugins
- Recuperação de informações de versão
Gerenciamento de Aplicações:
- Listar e filtrar aplicações por projeto, nome, namespace
- Obter informações detalhadas de uma aplicação
- Criar, atualizar e excluir aplicações
- Sincronizar aplicações com opções configuráveis
Cliente de API Robusto:
- Normalização de URL e tratamento inteligente de endpoints
- Tratamento abrangente de erros e mensagens de erro detalhadas
- Timeouts configuráveis e verificação SSL
- Proteção e mascaramento de segurança do token
Experiência do Desenvolvedor:
- Verificação estática completa de tipos com mypy
- Documentação detalhada e exemplos
- Configuração baseada em ambiente

Início Rápido

Configuração

# Clone the repository
git clone https://github.com/severity1/argocd-mcp.git
cd argocd-mcp

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install dependencies
uv pip install -e .

Iniciando o Servidor

O servidor é configurado por meio de variáveis de ambiente. Aqui estão as opções de configuração disponíveis:

Variável de Ambiente	Descrição	Valor Padrão
`ARGOCD_TOKEN`	Token da API do ArgoCD	None
`ARGOCD_API_URL`	Endpoint da API do ArgoCD	https://argocd.example.com/api/v1
`ARGOCD_VERIFY_SSL`	Verificar certificados SSL	true

Você pode iniciar o servidor de várias maneiras:

# Using MCP dev tools (provides debugging tools)
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
mcp dev server.py

# Using MCP run command
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
mcp run server.py

# Standard method
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
uv run server.py

# Setting multiple environment variables
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
export ARGOCD_API_URL=https://your-argocd-server.com:9000/api/v1
export ARGOCD_VERIFY_SSL=false  # Disable SSL verification for self-signed certs
uv run server.py

# Using a .env file
echo "ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
ARGOCD_API_URL=https://your-argocd-server.com:9000/api/v1
ARGOCD_VERIFY_SSL=false" > .env
uv run server.py

# Run in background
export ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN
uv run server.py > server.log 2>&1 & echo $! > server.pid

Quando o token é fornecido por meio de variável de ambiente, o Claude pode usá-lo sem que você precise especificá-lo em todos os comandos.

Conectando com o Claude

Usando a CLI do Claude Code

# Add the MCP server
claude mcp add argocd-mcp "uv run $(pwd)/server.py"

# With token
claude mcp add argocd-mcp -e ARGOCD_TOKEN=YOUR_ARGOCD_TOKEN -- "uv run $(pwd)/server.py"

# Verify it was added
claude mcp list

# For debugging, you can use MCP Inspector with 'mcp dev' command

Usando o Claude Desktop

Crie um arquivo de configuração claude_desktop_config.json:

{
  "mcpServers": {
    "argocd-mcp": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/path/to/argocd-mcp",
        "run",
        "server.py"
      ],
      "env": {
        "ARGOCD_TOKEN": "your_argocd_token",
        "ARGOCD_API_URL": "https://your-argocd-server.com/api/v1",
        "ARGOCD_VERIFY_SSL": "true"
      }
    }
  }
}

Substitua os caminhos e valores de configuração pelos seus valores reais:

Use o caminho completo para o executável uv (encontre-o com which uv no macOS/Linux ou where uv no Windows)
Defina o caminho correto do diretório para sua instalação do argocd-mcp
Adicione seu token da API do ArgoCD
Configure outras variáveis de ambiente conforme necessário

Essa configuração informa ao Claude Desktop como iniciar o servidor MCP automaticamente com suas configurações de ambiente específicas.

Ferramentas Disponíveis

Ferramentas de Sessão

get_user_info: Obtenha as informações do usuário atual via api/v1/session/userinfo

Ferramentas de Configurações

get_settings: Obtenha as configurações do servidor ArgoCD, incluindo UI, OIDC e outras configurações
get_plugins: Obtenha informações sobre os plugins ArgoCD configurados

Ferramentas de Versão

get_version: Obtenha informações de versão do servidor de API

Ferramentas de Gerenciamento de Aplicações

list_applications: Obtenha todas as aplicações com opções de filtro
get_application_details: Obtenha informações detalhadas sobre uma aplicação específica
create_application: Crie uma nova aplicação
update_application: Atualize uma aplicação existente
delete_application: Exclua uma aplicação
sync_application: Acione uma operação de sincronização em uma aplicação

Exemplos de Conversas

Verificando Informações do Usuário

User: What's my user information in ArgoCD?

Claude: Let me retrieve your user information.

⏺ argocd-mcp:get_user_info (MCP)
  ⎿  {"loggedIn": true, "username": "devops-user", "iss": "argocd"}

You are logged in as 'devops-user'.

Obtendo a Versão do ArgoCD

User: What version of ArgoCD is running on the server?

Claude: Let me check the ArgoCD version information.

⏺ argocd-mcp:get_version (MCP)
  ⎿  {
        "Version": "v2.9.3+5eaf684",
        "BuildDate": "2023-09-15T14:25:11Z",
        "GitCommit": "5eaf68452",
        "GitTreeState": "clean",
        "GoVersion": "go1.20.7",
        "Compiler": "gc",
        "Platform": "linux/amd64",
        "KustomizeVersion": "v5.1.1",
        "HelmVersion": "v3.12.3",
        "KubectlVersion": "v1.27.4",
        "JsonnetVersion": "v0.20.0"
      }

You're running ArgoCD v2.9.3, built on September 15, 2023. It's running on Linux (amd64) with Go 1.20.7, and includes Kustomize v5.1.1 and Helm v3.12.3.

Obtendo as Configurações do ArgoCD

User: Show me the ArgoCD server settings

Claude: Let me retrieve the ArgoCD server settings for you.

⏺ argocd-mcp:get_settings (MCP)
  ⎿  {
        "clusterSettings": {
          "appLabelKey": "argocd.argoproj.io/instance",
          "controllerNamespace": "argocd",
          "execEnabled": true,
          "statusBadgeEnabled": true,
          "uiBannerContent": "This is a development instance of ArgoCD",
          "url": "https://argocd.example.com"
        }
      }

Here are the key settings for your ArgoCD server:
- URL: https://argocd.example.com
- Controller namespace: argocd
- Exec enabled: Yes
- Status badge enabled: Yes
- UI Banner: "This is a development instance of ArgoCD"

Gerenciando Aplicações

User: What applications do I have in the "production" project?

Claude: Let me list your applications in the production project.

⏺ argocd-mcp:list_applications (MCP)
  ⎿  {
        "items": [
          {
            "metadata": {
              "name": "frontend-app",
            },
            "status": {
              "sync": {"status": "Synced"},
              "health": {"status": "Healthy"},
            }
          },
          {
            "metadata": {
              "name": "api-service",
            },
            "status": {
              "sync": {"status": "OutOfSync"},
              "health": {"status": "Healthy"},
            }
          },
          {
            "metadata": {
              "name": "database",
            },
            "status": {
              "sync": {"status": "Synced"},
              "health": {"status": "Degraded"},
            }
          }
        ]
      }

You have 3 applications in the production project:
- frontend-app (Synced, Healthy)
- api-service (OutOfSync, Healthy)
- database (Synced, Degraded)

User: Sync the api-service application

Claude: I'll sync the api-service application for you.

⏺ argocd-mcp:sync_application (MCP)
  ⎿  {
        "resourcesResult": {
          "updated": ["Deployment/api-service"],
          "hooks": []
        },
        "status": "Syncing"
      }

Application sync initiated successfully. The sync operation is now in progress.

Desenvolvimento

Requisitos

Python 3.12+
MCP (inclui FastMCP e ferramentas de desenvolvimento)
Gerenciador de pacotes uv (recomendado) ou pip
Token da API do ArgoCD

Verificação de Tipos

Este projeto usa mypy para verificação estática de tipos, a fim de melhorar a qualidade do código e detectar bugs relacionados a tipos antecipadamente:

# Install mypy
uv pip install mypy

# Run type checking
uv run -m mypy .

A configuração de verificação de tipos está disponível em pyproject.toml e mypy.ini. A configuração impõe regras estritas de tipagem, incluindo:

Proibindo definições sem tipo
Aviso ao retornar tipos Any
Verificando a completude das definições de funções
Suporte a pacotes de namespace
Configurações específicas de módulo

Estrutura do Projeto

O código é organizado em uma estrutura modular:

argocd-mcp/
├── api/              # API client and communication
│   ├── __init__.py
│   └── client.py     # HTTP client for ArgoCD API
├── models/           # Data models
│   ├── __init__.py
│   └── applications.py # Application data structures
├── tools/            # MCP tools implementation
│   ├── __init__.py
│   ├── session.py    # Session tools (user info)
│   ├── applications.py # Application management tools
│   ├── settings.py   # Server settings tools
│   └── version.py    # Version information tools
├── utils/            # Utility functions
│   ├── __init__.py
├── server.py         # Main server entry point
├── pyproject.toml    # Project configuration and dependencies
└── mypy.ini          # Mypy type checking configuration

Estendendo o Servidor

Para adicionar novos recursos:

Adicione novas ferramentas ao módulo apropriado no diretório tools
Registre novas ferramentas em server.py
Siga os padrões existentes para validação de parâmetros e tratamento de erros
Atualize a documentação no README.md
Adicione testes para novas funcionalidades

Solução de Problemas

Se você encontrar problemas:

Verifique os logs do servidor (o registro de informações está habilitado por padrão)
Observe que Processing request of type CallToolRequest é informativo, não um erro
Se estiver usando mcp dev server.py, o MCP Inspector abrirá automaticamente em http://localhost:5173 para depuração
Use os logs do servidor para depurar chamadas e respostas da API
Para problemas de certificado SSL com certificados autoassinados:

# Disable SSL verification
export ARGOCD_VERIFY_SSL=false
uv run server.py

Verifique se todas as variáveis de ambiente necessárias estão definidas corretamente:

# Show all current ArgoCD environment variables
env | grep ARGOCD

Contribuindo

Contribuições são bem-vindas! Abra uma issue ou pull request se quiser contribuir com este projeto.

Ao contribuir, siga estas diretrizes:

Garanta que todo o código inclua dicas de tipo adequadas
Execute a verificação de tipos do mypy antes de enviar PRs
Adicione testes para novas funcionalidades
Atualize a documentação para quaisquer novos recursos ou alterações