Servidor MCP de Homelab

👁 CI
👁 Python 3.12+
👁 License: MIT

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

🏆 Presentación para el Hackathon TestSprite Temporada 2

Rama: TestSprite_Hackathon | Tasa de éxito final: 10/10 (100%)

Qué he construido

homelab_mcp es un servidor MCP (Model Context Protocol); no habla REST. TestSprite prueba APIs REST. El desafío principal de esta presentación fue cerrar esa brecha de protocolo.

La solución: Un envoltorio (wrapper) de FastAPI que expone las 56 herramientas MCP como endpoints REST adecuados, completos con un contrato de errores HTTP documentado, para que TestSprite pueda ejercitar toda la superficie de herramientas sin ningún conocimiento del protocolo MCP.

TestSprite Agent → FastAPI wrapper (port 8080) → homelab_mcp tools → Infrastructure

Diseño del contrato de errores

En lugar de devolver errores 500 genéricos, el envoltorio implementa un contrato de errores HTTP de tres niveles:

El diseño de 424 Dependencia fallida es la parte más interesante. Las herramientas que se comunican con infraestructura real (hosts SSH, API de Proxmox, TrueNAS) ejecutan una prueba de pre-vuelo TCP antes de invocar al manejador. Si el destino es inalcanzable, el envoltorio devuelve un 424 con una carga útil estructurada — status, host, port, protocol y una sugerencia de remediación requires — sin tocar nunca el manejador. Sin ejecución parcial, sin fugas de credenciales a hosts inalcanzables.

Una vez que este contrato fue documentado en la especificación Swagger, TestSprite generó automáticamente casos de prueba de ruta negativa para los tres tipos de error.

Resultados de las pruebas — Arco de cinco ejecuciones

Correcciones entregadas por TestSprite

Ejecución de la suite de pruebas de TestSprite

# Clone the hackathon branch
git clone -b TestSprite_Hackathon https://github.com/washyu/homelab_mcp.git
cd homelab_mcp

# Install dependencies
uv sync

# Start the FastAPI wrapper (no auth mode for testing)
uv run python run_server.py --openapi --port 8080 --no-auth

# TestSprite test cases are in testsprite_tests/
# Run via the TestSprite agent pointed at http://localhost:8080

Lecciones aprendidas

1. Los servidores MCP necesitan una fachada REST para herramientas de prueba de API convencionales

2. Tu especificación Swagger es tu plan de pruebas — documenta los contratos de error y TestSprite generará pruebas para ellos

3. La precisión de code_summary.yaml importa — nombres de campo incorrectos producen pruebas incorrectas

4. Añade barandillas en CLAUDE.md antes de dejar que Claude Code se acerque a TestSprite — sin ellas, entrará autónomamente en un bucle de corregir→re-ejecutar y consumirá tus créditos

5. Excluye testsprite_tests/ de tu linter y formateador — trátalo como vendor/

6. Confirma o copia los informes después de cada ejecución — el resumen se sobrescribe cada vez

7. Los modos con y sin autenticación requieren ejecuciones separadas — no se pueden cubrir ambos en una sola sesión de TestSprite

Artículo completo: shaunjackson.space

Un servidor MCP de Python que permite a los asistentes de IA gestionar, desplegar y monitorear la infraestructura de un 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 clave

• 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 más descubrimiento de scripts de la comunidad

• Ciclo de vida de VM/Contenedor -- 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 gestionados por estado con detección de deriva 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 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 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 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 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 las credenciales: add (crear/actualizar — upsert), list (leer), remove (eliminar). No hay 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 SO no está disponible (servidores sin cabeza), las credenciales recurren a las variables de entorno.

Consulta la referencia de la CLI de credenciales para obtener la documentación completa.

Configuración del cliente MCP

Desde PyPI (uvx) — recomendado:

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

Desde clon de 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
testsprite_tests/ # TestSprite generated test suite (hackathon)
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 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 (pull request)

Licencia

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

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• analyze_network_topologyB
• bulk_discover_and_mapA
• check_ansible_serviceB
• check_service_requirementsA
• clone_proxmox_vmB
• control_vmB
• create_infrastructure_backupC
• create_proxmox_lxcB