Servidor MCP de Homelab

Gestión de infraestructura de Homelab impulsada por IA a través del Protocolo de Contexto de Modelo (MCP)

Un servidor MCP en Python que permite a los asistentes de IA gestionar, desplegar y monitorizar la infraestructura de un homelab. Las herramientas abarcan el descubrimiento por SSH, la gestión de máquinas virtuales, la instalación de servicios, el mapeo de topología de red, operaciones en Proxmox y la gestión de credenciales.

Características principales

• Descubrimiento SSH -- Recopila información completa de hardware y software de cualquier sistema

• Instalación de servicios -- Despliega Jellyfin, Pi-hole, Ollama, Home Assistant y más a partir de plantillas

• Integración con Proxmox -- Acceso completo a la API además del descubrimiento de scripts de la comunidad

• Ciclo de vida de VM/Contenedores -- Despliega, controla y elimina cargas de trabajo de Docker y LXD

• Mapeo de red -- Descubre dispositivos, analiza la topología y rastrea cambios

• Terraform y Ansible -- Despliegues con gestión de estado, detección de desviaciones y playbooks

• Gestión de credenciales -- Registra servidores una vez, conéctate sin volver a introducir credenciales

Inicio rápido

# Install from PyPI (recommended — no clone needed)
uvx homelab-mcp

# Or clone and run from source
git clone https://github.com/washyu/homelab_mcp.git
cd homelab_mcp
uv sync && uv run python run_server.py

Para ver el tutorial completo (variables de entorno, configuración del cliente MCP, primera llamada a herramienta), consulta la Guía de configuración.

Documentación

Cómo funciona

1. Configuración -- El servidor genera un par de claves SSH en la primera ejecución (~/.ssh/mcp_admin_rsa)

2. Incorporar un host -- Usa setup_mcp_admin para crear un usuario gestionado en el sistema de destino

3. Verificar -- Usa verify_mcp_admin para confirmar el acceso SSH sin contraseña

4. Gestionar -- Descubre hardware, instala servicios, controla máquinas virtuales y mapea tu red

El servidor se comunica a través de stdio utilizando el protocolo MCP. Conéctalo a cualquier cliente compatible con MCP (Claude Desktop, etc.) e interactúa mediante lenguaje natural.

Gestión de credenciales

Almacena las credenciales de SSH y Proxmox una vez para que el servidor las inyecte automáticamente en cada conexión:

# Store an SSH credential
homelab-mcp credentials add 192.168.1.10 admin

# Store a Proxmox API credential
homelab-mcp credentials add 192.168.1.200 root@pam --type proxmox

# List stored credentials
homelab-mcp credentials list
homelab-mcp credentials list --type proxmox

# Remove a credential
homelab-mcp credentials remove 192.168.1.10

Las credenciales se almacenan en el llavero del sistema operativo (libsecret en Linux, Keychain en macOS). Cuando el llavero del sistema operativo no está disponible (servidores sin interfaz gráfica), las credenciales recurren a las variables de entorno.

Consulta la Referencia de CLI de credenciales para ver la documentación completa.

Configuración del cliente MCP

Desde PyPI (uvx) — recomendado:

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

Desde el clon del código fuente:

{
  "mcpServers": {
    "homelab": {
      "command": "uv",
      "args": ["run", "python", "run_server.py"],
      "cwd": "/path/to/homelab_mcp"
    }
  }
}

Desarrollo

# Install with dev dependencies
uv sync --group dev

# Run tests (unit only, no Docker required)
uv run pytest tests/ -m "not integration"

# Code quality
uv run ruff check src/ tests/
uv run mypy src/

Consulta DEPLOYMENT.md para obtener detalles sobre el despliegue en producción.

Estructura del proyecto

src/homelab_mcp/
  server.py              # MCP server with JSON-RPC protocol
  tool_schemas/          # Tool definitions (8 schema files)
  tool_annotations.py    # MCP annotation hints per tool
  ssh_tools.py           # SSH discovery and hardware detection
  service_installer.py   # Service installation framework
  infrastructure_crud.py # Infrastructure lifecycle management
  vm_operations.py       # VM/container operations
  sitemap.py             # Network topology mapping
  database.py            # SQLite device tracking
  error_handling.py      # Centralized error handling
  credential_store.py    # OS keyring credential storage
  log_filter.py          # Credential redaction for log output
  prompt_registry.py     # MCP prompts registry
  resource_readers.py    # MCP resource read handlers
  service_templates/     # YAML service definitions
tests/                   # Unit and integration tests
docs/                    # Full documentation

Agradecimientos

Integración de scripts de la comunidad de Proxmox impulsada por community-scripts/ProxmoxVE (Licencia MIT).

Contribución

1. Haz un fork del repositorio

2. Crea una rama de funcionalidad

3. Escribe pruebas para la nueva funcionalidad

4. Asegúrate de que todas las pruebas pasen

5. Envía una solicitud de extracción (pull request)

Licencia

Licencia MIT -- consulta el archivo LICENSE para más detalles.