Homelab MCP Server

Servidor MCP Homelab

Gestión de Infraestructura Homelab Impulsada por IA mediante el Protocolo de Contexto de Modelos

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

Características Principales

• Descubrimiento SSH -- Recopila información integral de hardware y software de cualquier sistema
• Instalación de Servicios -- Implementa Jellyfin, Pi-hole, Ollama, Home Assistant y más desde plantillas
• Integración con Proxmox -- Acceso completo a la API más descubrimiento de scripts de la comunidad
• Ciclo de Vida de VM/Contenedores -- Implementa, controla y elimina cargas de trabajo Docker y LXD
• Mapeo de Red -- Descubre dispositivos, analiza topología y rastrea cambios
• Terraform y Ansible -- Implementaciones gestionadas por estado con detección de desviaciones y playbooks
• Gestión de Credenciales -- Registra servidores una vez, conéctate sin volver a ingresar 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 el tutorial completo (variables de entorno, configuración del cliente MCP, primera llamada a herramienta), consulta la Guía de Configuración.

Documentación

Guía	Descripción
Guía de Configuración	De cero a la primera llamada a herramienta
Referencia de Herramientas	Todas las herramientas con argumentos y ejemplos
Configuración	Variables de entorno y opciones de CLI
Configuración de Claude Desktop	Guía de integración con Claude Desktop
Servicio HTTP	Modo REST/OpenAPI, endpoints y contrato de errores

Cómo Funciona

1. Configuración -- El servidor genera un par de claves SSH en la primera ejecución (~/.ssh/mcp_admin_rsa)
2. Registra un host -- Usa setup_mcp_admin para crear un usuario gestionado en el sistema de destino
3. Verifica -- Usa verify_mcp_admin para confirmar el acceso SSH sin contraseña
4. Gestiona -- Descubre hardware, instala servicios, controla VMs y mapea tu red

El servidor se comunica a través de stdio usando 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 credenciales SSH y de Proxmox una sola 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 an SSH key-based credential (stores the key file path in the keyring, not the key)
homelab-mcp credentials add 192.168.1.10 admin --key-path ~/.ssh/id_ed25519

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

# Update an existing credential — `add` is upsert; re-running replaces the stored entry
homelab-mcp credentials add 192.168.1.10 admin

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

# Remove a credential
homelab-mcp credentials remove 192.168.1.10

La CLI proporciona CRUD completo sobre credenciales: add (crear/actualizar — upsert), list (leer), remove (eliminar). No existe un subcomando update separado — volver a ejecutar add reemplaza tanto el secreto del llavero como el tipo de autenticación de la entrada del registro.

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 se respaldan en variables de entorno.

Consulta la referencia CLI de Credenciales para documentación completa.

Configuración del Cliente MCP

Desde PyPI (uvx) — recomendado:

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

Desde clon de la 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 detalles de implementación 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).

Contribuciones

1. Haz un fork del repositorio
2. Crea una rama de características
3. Escribe pruebas para la nueva funcionalidad
4. Asegúrate de que todas las pruebas pasen
5. Envía una solicitud de extracción

Licencia

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