Servidor MCP de ArgoCD

Un servidor MCP (Protocolo de contexto de modelo) que se integra con la API de ArgoCD, lo que permite que los asistentes de IA y los modelos de lenguaje grandes administren aplicaciones y recursos de ArgoCD a través de interacciones de lenguaje natural.

Características

Autenticación y gestión de sesiones :
- Recuperación de información de usuario desde la API de ArgoCD
- Autenticación basada en tokens con ArgoCD
- Configuración del servidor y acceso a la configuración
- Recuperación de información del complemento
- Recuperación de información de la versión
Gestión de aplicaciones :
- Enumere y filtre aplicaciones por proyecto, nombre y espacio de nombres
- Obtenga información detallada de la aplicación
- Crear, actualizar y eliminar aplicaciones
- Sincronizar aplicaciones con opciones configurables
Cliente API robusto :
- Normalización de URL y manejo inteligente de puntos finales
- Manejo integral de errores y mensajes de error detallados
- Tiempos de espera configurables y verificación SSL
- Protección y enmascaramiento de seguridad de tokens
Experiencia de desarrollador :
- Comprobación completa de tipos estáticos con mypy
- Documentación detallada y ejemplos
- Configuración basada en el entorno

Inicio rápido

Configuración

# Clone the repository
git clone https://github.com/yourusername/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 el servidor

El servidor se configura mediante variables de entorno. Estas son las opciones de configuración disponibles:

Variable de entorno	Descripción	Valor predeterminado
`ARGOCD_TOKEN`	Token de API de ArgoCD	Ninguno
`ARGOCD_API_URL`	Punto final de la API de ArgoCD	https://argocd.example.com/api/v1
`ARGOCD_VERIFY_SSL`	Verificar certificados SSL	verdadero

Puedes iniciar el servidor de varias maneras:

# 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

Cuando el token se proporciona a través de una variable de entorno, Claude puede usarlo sin tener que especificarlo en cada comando.

Conectando con Claude

Uso de la CLI de 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

Uso de Claude Desktop

Cree un archivo de configuración 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"
      }
    }
  }
}

Reemplace las rutas y los valores de configuración con sus valores reales:

Utilice la ruta completa al ejecutable uv (encuéntrelo con which uv en macOS/Linux o where uv en Windows)
Establezca la ruta de directorio correcta para su instalación de argocd-mcp
Agregue su token API de ArgoCD
Configurar otras variables de entorno según sea necesario

Esta configuración le dice a Claude Desktop cómo iniciar el servidor MCP automáticamente con su configuración de entorno específica.

Herramientas disponibles

Herramientas de sesión

get_user_info : obtiene la información del usuario actual a través de api/v1/session/userinfo

Herramientas de configuración

get_settings : obtiene la configuración del servidor ArgoCD, incluida la interfaz de usuario, OIDC y otras configuraciones
get_plugins : obtiene información sobre los complementos de ArgoCD configurados

Herramientas de versión

get_version : Obtener información de la versión del servidor API

Herramientas de gestión de aplicaciones

list_applications : Obtener todas las aplicaciones con opciones de filtrado
get_application_details : Obtenga información detallada sobre una aplicación específica
create_application : Crea una nueva aplicación
update_application : Actualizar una aplicación existente
delete_application : Eliminar una aplicación
sync_application : activa una operación de sincronización en una aplicación

Conversaciones de ejemplo

Comprobación de la información del usuario

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'.

Obtener la versión de 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.

Obtener la configuración de 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"

Administrar aplicaciones

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.

Desarrollo

Requisitos

Python 3.12+
MCP (incluye FastMCP y herramientas de desarrollo)
Gestor de paquetes uv (recomendado) o pip
Token de API de ArgoCD

Comprobación de tipos

Este proyecto utiliza mypy para la verificación de tipos estáticos para mejorar la calidad del código y detectar errores relacionados con los tipos de forma temprana:

# Install mypy
uv pip install mypy

# Run type checking
uv run -m mypy .

La configuración de verificación de tipos está disponible tanto en pyproject.toml como mypy.ini . Esta configuración aplica reglas de tipado estrictas, incluyendo:

No permitir definiciones sin tipo
Advertencia sobre la devolución de cualquier tipo
Comprobación de la integridad de las definiciones de funciones
Compatibilidad con paquetes de espacios de nombres
Configuraciones específicas del módulo

Estructura del proyecto

El código está organizado en una estructura 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

Ampliación del servidor

Para agregar nuevas funciones:

Agregue nuevas herramientas al módulo apropiado en el directorio tools
Registrar nuevas herramientas en server.py
Siga los patrones existentes para la validación de parámetros y el manejo de errores.
Actualizar la documentación en README.md
Agregar pruebas para nuevas funcionalidades

Solución de problemas

Si encuentra problemas:

Comprobar los registros del servidor (el registro de información está habilitado de forma predeterminada)
Tenga en cuenta que Processing request of type CallToolRequest es informativa, no un error.
Si usa mcp dev server.py , el Inspector MCP se abrirá automáticamente en http://localhost:5173 para depuración
Utilice los registros del servidor para depurar llamadas y respuestas de API
Para problemas de certificados SSL con certificados autofirmados:

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

Compruebe si todas las variables de entorno necesarias están configuradas correctamente:

# Show all current ArgoCD environment variables
env | grep ARGOCD

Contribuyendo

¡Agradecemos sus contribuciones! Si desea contribuir a este proyecto, abra un problema o una solicitud de incorporación de cambios.

Al contribuir, siga estas pautas:

Asegúrese de que todo el código incluya sugerencias de tipo adecuadas
Ejecute la comprobación de tipos de mypy antes de enviar solicitudes de solicitud
Agregar pruebas para nuevas funcionalidades
Actualizar la documentación para cualquier característica o cambio nuevo

argocd-mcp

Integrations