CloudStack MCP Server

Integra con Apache CloudStack para gestionar recursos en la nube directamente desde tu escritorio.

GitHubPrueba este MCPPatrocinado

Documentación

CloudStack MCP Server

Version License TypeScript

Un servidor integral del Protocolo de Contexto de Modelos (MCP) que proporciona una gestión completa de la infraestructura CloudStack mediante interacciones en lenguaje natural con Claude Desktop. Esta implementación ofrece una amplia cobertura de las APIs de CloudStack 4.20 con más de 477 herramientas MCP que abarcan más de 735 métodos de API en 32 categorías.

Descripción general

El CloudStack MCP Server permite una gestión fluida de la infraestructura en la nube al conectar las APIs de CloudStack con la interfaz de lenguaje natural de Claude. Los usuarios pueden realizar operaciones complejas de infraestructura mediante comandos conversacionales, eliminando la necesidad de aprender la sintaxis de la API de CloudStack o las herramientas de línea de comandos.

Estadísticas clave:

  • Cobertura extensa de API: más de 477 herramientas MCP que cubren más de 735 métodos de API de CloudStack (93% de cobertura)
  • Categorías completas: 32 categorías de API de CloudStack implementadas, incluidas nuevas funciones de infraestructura
  • Seguridad empresarial: 96 operaciones peligrosas protegidas con sistema de confirmación
  • Interfaz de lenguaje natural: curva de aprendizaje cero para la gestión de infraestructura
  • Listo para producción: fiabilidad de nivel empresarial con controles de seguridad integrales

Características

🏗️ Gestión de infraestructura

  • Operaciones de máquinas virtuales: gestión completa del ciclo de vida, incluidos despliegue, escalado, migración y monitoreo
  • Gestión de almacenamiento: operaciones de volúmenes, gestión de instantáneas, capacidades de copia de seguridad y restauración
  • Gestión de almacén de imágenes: gestión completa del almacenamiento backend con soporte para NFS, S3 y Swift
  • Gestión de pods: operaciones de pods de infraestructura, incluida la creación, dedicación y gestión de rangos de IP
  • Administración de redes: gestión de VPC, balanceo de carga, reglas de firewall y ACL de red
  • Grupos de seguridad: gestión de reglas de entrada/salida y aplicación de políticas de seguridad

👥 Gestión de identidad y acceso

  • Administración de cuentas: gestión del ciclo de vida de usuarios con control de acceso basado en roles
  • Gestión de dominios: estructuras jerárquicas de dominios y organización de recursos
  • Gestión de proyectos: espacios de colaboración multiinquilino con asignaciones de usuarios
  • Integración LDAP: sincronización con servicios de directorio empresarial

🌐 Redes avanzadas

  • VPC y redes: configuración y gestión de nubes privadas virtuales
  • Servicios VPN: conectividad VPN de sitio a sitio y de acceso remoto
  • Balanceo de carga: configuración del balanceador de carga de aplicaciones con comprobaciones de estado
  • Gestión de certificados SSL: ciclo de vida completo de certificados, incluida la emisión, carga, revocación y gestión de proveedores de CA

📊 Monitoreo y análisis

  • Métricas de recursos: monitoreo del rendimiento de la infraestructura y planificación de capacidad
  • Gestión de eventos: seguimiento de eventos del sistema y configuración de alertas
  • Gestión de cuotas: aplicación de límites de recursos e integración de facturación
  • Gestión de AutoScale: políticas de escalado automático y umbrales de rendimiento

🔧 Funciones avanzadas

  • Gestión de plantillas e ISO: ciclo de vida de imágenes con replicación entre zonas
  • Integración de Kubernetes: gestión de plataformas de orquestación de contenedores
  • Almacenamiento de objetos: almacenamiento compatible con S3 con políticas de ciclo de vida
  • Integración de hardware: gestión de NetScaler, UCS y servidores de metal desnudo
  • Tungsten Fabric SDN: redes definidas por software con microsegmentación

🛡️ Seguridad y protección empresarial

  • Confirmación de acciones peligrosas: sistema de confirmación a prueba de errores que protege 96 operaciones destructivas
  • Detección inteligente de operaciones: identificación automática de operaciones de eliminación, destrucción, purga, escalado y reinicio
  • Advertencias con contexto enriquecido: descripciones detalladas de operaciones con niveles de gravedad y evaluación de impacto
  • Requisitos de confirmación: confirmación escrita obligatoria para operaciones críticas (p. ej., "destruir permanentemente")
  • Protección de infraestructura: protecciones críticas para la eliminación de almacenes de imágenes y operaciones de gestión de pods
  • Controles de entorno: omisiones inteligentes para desarrollo mientras se aplica seguridad en producción
  • Auditoría integral: pistas de auditoría de seguridad completas con seguimiento de correlación e informes de cumplimiento
  • Categorías de operaciones: protección en operaciones de VM, almacenamiento, red, VPC, Kubernetes, infraestructura y certificados
  • Gestión de memoria: seguimiento eficiente con limpieza automática y políticas de tiempo de espera configurables

Cobertura de pruebas y garantía de calidad

Marco de pruebas de nivel empresarial (v2.3.0+)

  • Suite de pruebas completa: 12 archivos de pruebas de integración que cubren todas las operaciones empresariales
  • Más de 350 casos de prueba: pruebas sistemáticas en operaciones de VM, almacenamiento, red, cuentas, Kubernetes, balanceador de carga, VPN, plantillas/ISO, administración del sistema, seguridad/cumplimiento, monitoreo/análisis e integración empresarial
  • Marco de simulación avanzado: clase TestFramework personalizada con más de 50 simulaciones de métodos de cliente de CloudStack
  • Manejo completo de errores: pruebas para errores de API, tiempos de espera de red, problemas de permisos y restricciones de recursos
  • Cobertura de operaciones CRUD: patrones de crear, leer, actualizar y eliminar para todos los tipos de recursos
  • Pruebas de casos límite: validación integral de condiciones de error y escenarios límite

Estructura de pruebas

tests/
├── helpers/TestFramework.ts             # Comprehensive mocking and utilities
├── integration/
│   ├── vm-operations.test.ts            # 25+ VM lifecycle tests
│   ├── storage-operations.test.ts       # 20+ Storage and snapshot tests
│   ├── network-operations.test.ts       # 25+ Network and security tests
│   ├── account-management.test.ts       # 20+ User and domain tests
│   ├── kubernetes-operations.test.ts    # 14+ K8s cluster tests
│   ├── load-balancer-operations.test.ts # 18+ Load balancer tests
│   ├── vpn-operations.test.ts           # 14+ VPN and gateway tests
│   ├── template-iso-operations.test.ts  # 16+ Template and ISO tests
│   ├── system-administration.test.ts    # 20+ System admin tests
│   ├── security-compliance.test.ts      # 18+ Security and compliance tests
│   ├── monitoring-analytics.test.ts     # 15+ Monitoring and analytics tests
│   └── enterprise-integration.test.ts   # 12+ Enterprise integration tests
└── unit/cloudstack/client.test.ts       # CloudStack client tests

Métricas de calidad

  • Cobertura de pruebas: más de 350 casos de prueba en 12 categorías principales de operaciones
  • Escenarios de error: más de 80 pruebas de manejo de errores y casos límite
  • Cobertura de simulaciones: todos los métodos de API de CloudStack simulados sistemáticamente con más de 65 métodos de cliente de Fase 3
  • Operaciones empresariales: cobertura completa de administración del sistema, seguridad/cumplimiento, monitoreo/análisis e integración empresarial
  • Listo para CI/CD: integración completa de Jest con informes de cobertura

Instalación

Requisitos previos

  • Node.js: versión 18.0 o superior
  • Claude Desktop: última versión con soporte MCP
  • Acceso a CloudStack: credenciales de API válidas con los permisos adecuados

Paso 1: Clonar y compilar

# Clone the repository
git clone https://github.com/mozg31337/cloudstack-mcp-server.git
cd cloudstack-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Paso 2: Configurar la conexión a CloudStack

🔒 Configuración segura con variables de entorno (recomendado)

Por seguridad, use variables de entorno en lugar de credenciales codificadas:

# Copy the example environment file
cp .env.example .env

# Edit .env with your CloudStack credentials
# The .env file is automatically excluded from git

Edite .env con sus credenciales reales:

# Production CloudStack Environment
CLOUDSTACK_PROD_NAME="Production CloudStack"
CLOUDSTACK_PROD_API_URL="https://your-cloudstack.example.com/client/api"
CLOUDSTACK_PROD_API_KEY="your-production-api-key"
CLOUDSTACK_PROD_SECRET_KEY="your-production-secret-key"

# Development CloudStack Environment
CLOUDSTACK_DEV_NAME="Development CloudStack"
CLOUDSTACK_DEV_API_URL="https://dev-cloudstack.example.com/client/api"
CLOUDSTACK_DEV_API_KEY="your-dev-api-key"
CLOUDSTACK_DEV_SECRET_KEY="your-dev-secret-key"

# Default environment to use
CLOUDSTACK_DEFAULT_ENVIRONMENT="default"

Alternativa: configuración basada en archivos

Si prefiere la configuración basada en archivos (no recomendada para producción):

# Copy example configuration
cp config/cloudstack.example.json config/cloudstack.json

Edite config/cloudstack.json con valores de marcador de posición (las credenciales reales deben estar en variables de entorno):

{
  "defaultEnvironment": "default",
  "environments": {
    "default": {
      "name": "Production CloudStack",
      "apiUrl": "https://your-cloudstack.example.com/client/api",
      "apiKey": "your-api-key-here",
      "secretKey": "your-secret-key-here",
      "timeout": 30000,
      "retries": 3
    }
  },
  "logging": {
    "level": "info",
    "file": "logs/cloudstack-mcp.log"
  }
}

Paso 3: Integración con Claude Desktop

Agregue el servidor MCP a la configuración de Claude Desktop:

macOS/Linux: ~/.config/claude/claude_desktop_config.json Windows: %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "cloudstack": {
      "command": "node",
      "args": ["/absolute/path/to/cloudstack-mcp-server/dist/server.js"],
      "env": {
        "CLOUDSTACK_CONFIG": "/absolute/path/to/config/cloudstack.json"
      }
    }
  }
}

Paso 4: Verificar la instalación

  1. Reinicie Claude Desktop
  2. Inicie una nueva conversación
  3. Pruebe la conexión con: "Lista mis máquinas virtuales de CloudStack"

Configuración

Variables de entorno

El servidor admite una configuración integral mediante variables de entorno para la gestión segura de credenciales:

Entorno de producción:

CLOUDSTACK_PROD_NAME="Production CloudStack"
CLOUDSTACK_PROD_API_URL="https://cloudstack.example.com/client/api"
CLOUDSTACK_PROD_API_KEY="your-production-api-key"
CLOUDSTACK_PROD_SECRET_KEY="your-production-secret-key"
CLOUDSTACK_PROD_TIMEOUT=30000
CLOUDSTACK_PROD_RETRIES=3

Entorno de desarrollo:

CLOUDSTACK_DEV_NAME="Development CloudStack"
CLOUDSTACK_DEV_API_URL="https://dev-cloudstack.example.com/client/api"
CLOUDSTACK_DEV_API_KEY="your-dev-api-key"
CLOUDSTACK_DEV_SECRET_KEY="your-dev-secret-key"
CLOUDSTACK_DEV_TIMEOUT=30000
CLOUDSTACK_DEV_RETRIES=3

Control de configuración:

# Default environment to use ("default" for production, "dev" for development)
CLOUDSTACK_DEFAULT_ENVIRONMENT="default"

# Logging configuration
CLOUDSTACK_LOG_LEVEL=info
CLOUDSTACK_LOG_FILE=logs/cloudstack-mcp.log

# Legacy configuration file path (optional)
CLOUDSTACK_CONFIG=/path/to/cloudstack.json

# Network settings
CLOUDSTACK_TIMEOUT=30000
CLOUDSTACK_RETRIES=3

Múltiples entornos

Configure múltiples entornos de CloudStack para diferentes casos de uso:

{
  "defaultEnvironment": "production",
  "environments": {
    "production": { "..." },
    "development": { "..." },
    "testing": { "..." }
  }
}

Cambie de entorno en Claude especificando: "Lista las VMs en el entorno de desarrollo"

Ejemplos de uso

Descubrimiento de infraestructura

"List all virtual machines in zone-east"
"Show me running VMs with their IP addresses"
"What storage volumes are available?"
"Display network configuration for my VPC"
"List all image store backends"
"Show pods in my zone"

Gestión de máquinas virtuales

"Deploy a new Ubuntu 20.04 server with 4GB RAM"
"Start virtual machine vm-12345"
"Create a snapshot of my database server"
"Resize VM memory to 8GB"

Operaciones de red

"Create a load balancer for web servers"
"Add firewall rule allowing HTTP traffic"
"Configure VPN access for remote users"
"Set up network ACL for database tier"

Gestión de seguridad

"Create security group for web applications"
"Allow SSH access from corporate network"
"Upload SSL certificate for HTTPS load balancer"
"Issue a Let's Encrypt certificate for my domain"
"List available certificate authorities"
"Configure two-factor authentication"

Gestión de infraestructura

"Add a new NFS image store backend"
"Create a pod for my zone with IP range 192.168.1.10-100"
"Add S3 bucket as image store with my AWS credentials"
"Dedicate pod to specific domain"
"Update pod IP range configuration"

Desarrollo

Configuración de desarrollo local

# Development mode with hot reload
npm run dev

# Run test suite
npm test

# Test with coverage report
npm run test:coverage

# Code linting
npm run lint

# Type checking
npm run typecheck

Estructura del proyecto

src/
├── server.ts              # MCP server implementation with 477+ tools
├── cloudstack/
│   ├── client.ts          # CloudStack API client with 735+ methods
│   ├── auth.ts            # HMAC signature authentication
│   └── types.ts           # TypeScript type definitions
├── utils/
│   ├── config.ts          # Configuration management
│   └── logger.ts          # Structured logging
├── security/              # Enterprise security framework
├── tests/                 # Comprehensive test suite
└── config/                # Configuration templates

Cobertura de API

Estado completo de implementación

CategoríaMétodos de APIHerramientas MCPCobertura
Máquina virtual7280100%
Almacenamiento y volúmenes10528100%
Redes8559100%
Balanceador de carga3430100%
Seguridad2219100%
Gestión de cuentas1617100%
Plantillas e ISO3525100%
AutoScale2121100%
Almacén de imágenes206100%
Gestión de pods95100%
Gestión de certificados104100%
Total735+477+93%

Para un análisis detallado de la cobertura de API, consulte la Documentación de cobertura de API.

Hoja de ruta futura

Mejoras de alta prioridad

  • Arquitectura: organización modular de herramientas e implementación de carga diferida
  • Rendimiento: agrupación de conexiones y estrategias inteligentes de caché
  • Pruebas: mayor cobertura de pruebas y suite de pruebas de integración
  • Seguridad: rotación de claves de API y control de acceso basado en roles

Funciones de prioridad media

  • Monitoreo: comprobaciones de estado, recopilación de métricas y registro de auditoría
  • Empresarial: aislamiento multiinquilino y automatización de copias de seguridad
  • Desarrollo: tipos TypeScript integrales y documentación

Mejoras futuras

  • CloudStack 5.x: compatibilidad con la API cuando esté disponible
  • Interfaz de usuario: panel web y herramientas de línea de comandos
  • Integración de IA: optimización de recursos y gestión de costos
  • Tiempo real: transmisión de eventos y actualizaciones en vivo

Consulte la hoja de ruta completa en nuestra lista de tareas de desarrollo.

Contribuciones

Agradecemos las contribuciones para mejorar el CloudStack MCP Server:

  1. Haga un fork del repositorio y cree una rama de características
  2. Implemente los cambios con las pruebas adecuadas
  3. Ejecute las comprobaciones de calidad: npm run lint && npm test
  4. Envíe una solicitud de extracción con una descripción detallada

Directrices de desarrollo

  • Siga las mejores prácticas de TypeScript
  • Mantenga la cobertura de pruebas por encima del 90%
  • Incluya documentación para nuevas funciones
  • Use mensajes de confirmación convencionales

Consideraciones de seguridad

  • Credenciales de API: almacénelas de forma segura y rote regularmente
  • Acceso a la red: use HTTPS para todas las comunicaciones con CloudStack
  • Permisos: siga el principio de privilegio mínimo
  • Registro de auditoría: actívelo para entornos de producción

Licencia

Este proyecto está licenciado bajo la Licencia Internacional Creative Commons Attribution-NonCommercial-ShareAlike 4.0. Consulte LICENCIA para obtener más detalles.

Uso comercial: comuníquese con los mantenedores para conocer las opciones de licencia comercial.

Soporte

  • Problemas: informe errores a través de GitHub Issues
  • Documentación: consulte el directorio docs/ para obtener guías detalladas
  • Comunidad: participe en las discusiones de nuestro repositorio

Nota: esta aplicación utiliza técnicas de desarrollo asistido por IA. Aunque se ha probado exhaustivamente, revise y valide la funcionalidad para su entorno específico antes del despliegue en producción.