MCP Hub

Un único servidor MCP que da a tu asistente de IA las llaves de todo tu homelab.

MCP Hub es un único servidor Model Context Protocol que se sitúa en una máquina de tu red y desde allí se expande: SSH a cada host de tu flota, contenedores Proxmox, Docker, Synology DSM, túneles Cloudflare y DNS, flujos de trabajo n8n, Notion, tu bóveda de contraseñas. En lugar de ejecutar una docena de servidores MCP y cablear cada uno en tu cliente, ejecutas uno y apuntas tu asistente a él.

"¿Por qué Jellyfin no es accesible?" — y el asistente comprueba el contenedor, lee el diario, nota que el túnel de entrada está obsoleto, lo arregla y te dice lo que ha hecho.

⚠️ Lee SECURITY.md antes de desplegar esto. MCP Hub otorga a una LLM acceso root shell a través de tu flota. Ese es el objetivo, y es genuinamente peligroso. Los valores predeterminados son seguros (127.0.0.1, solo lectura); el peligro comienza cuando los cambias.

Demostración de resolución de problemas

El repositorio incluye una grabación Asciinema saneada de una sesión completa de resolución de problemas basada en observación: endpoint fallido, diagnóstico systemd, plan de mutación exacto, confirmación explícita, reinicio y comprobaciones de salud finales. Utiliza el inventario de ejemplo y no contiene datos de infraestructura privados.

asciinema play docs/troubleshooting.cast

Consulta la grabación directamente cuando Asciinema no esté instalado; el formato cast es JSON delimitado por saltos de línea y sigue siendo revisable.

Related MCP server: homelab-mcp

Contenido

• Características

• Inicio rápido

• Despliegue

• Pruebas locales

• Diagnósticos de rescate

• Configuración

• Referencia de herramientas

• Seguridad

• Versionado

• Contribuir

Características

• 111 herramientas, un endpoint, un archivo de configuración.

• Basado en configuración. Tu red vive en hosts.yaml y .env. Nada sobre tu infraestructura está integrado en el código.

• SSH multiplexado. Sockets de control persistentes, por lo que los comandos en toda la flota tardan milisegundos en lugar de un handshake TCP cada uno.

• Integraciones opcionales. Cada integración está desactivada por defecto y se activa con una sola bandera. Ejecútalo como una herramienta de flota SSH pura si eso es todo lo que quieres.

• Secretos conectables. Lee credenciales del entorno, o de una bóveda Bitwarden/Vaultwarden a través de bw serve.

• Autenticación por token Bearer sobre una ruta de endpoint imposible de adivinar.

• Modo global de solo lectura, activado por defecto: una bandera desactiva las 43 herramientas mutantes, aplicado de forma centralizada en lugar de herramienta por herramienta.

• Redacción automática de secretos en lecturas de archivos y salida de comandos.

• Trabajos en segundo plano con sondeo, registros y un almacén de estado SQLite persistente.

Inicio rápido

Requiere Python 3.11+ y un host Linux con acceso SSH a las máquinas que quieras gestionar.

git clone https://github.com/wnx82/mcp-hub.git
cd mcp-hub

python3 -m venv .venv && . .venv/bin/activate
pip install -e .

cp .env.example .env                  # then edit — see below
cp hosts.example.yaml hosts.yaml      # then edit: your fleet
chmod 600 .env hosts.yaml

python server.py

Como mínimo, establece estos dos en .env:

MCP_SECRET_PATH=/$(openssl rand -hex 16)   # unguessable endpoint path
MCP_AUTH_TOKEN=$(openssl rand -hex 32)     # bearer token — the real auth

El servidor entonces escucha en http://127.0.0.1:8000<MCP_SECRET_PATH>, con MCP_READ_ONLY=true. Apunta tu cliente MCP a esa URL y envía Authorization: Bearer <MCP_AUTH_TOKEN>. Las solicitudes sin el token reciben un 401; las solicitudes a cualquier otra ruta reciben un 404.

Para un cliente MCP local que quiera stdio en lugar de HTTP, inicia el mismo hub con:

mcp-hub --transport stdio

o establece MCP_TRANSPORT=stdio en el entorno antes del lanzamiento.

Para un despliegue con systemd, sudo ./deploy/install.sh crea un usuario dedicado mcphub y una clave SSH, genera ambos secretos en /etc/default/mcp-hub, e instala la unidad. Es idempotente y nunca sobrescribe la configuración existente. Consulta deploy/.

Para una configuración completa de Claude Code, manejo seguro de tokens, comprobaciones de conexión, un primer prompt de solo lectura y la limitación actual de Claude Desktop, consulta Conectar MCP Hub a Claude.

Si quieres que tu asistente entienda tu topología privada, roles de host, ventanas de cambio y reglas operativas de MCP sin comprometer ninguno de esos datos, comienza desde PROJECT_INSTRUCTIONS.example.md y mantén tu PROJECT_INSTRUCTIONS.md personalizado solo local.

Despliegue

MCP Hub soporta tres modos de ejecución:

El paquete Python y la ejecución directa usan el checkout actual y su virtualenv. No crean una cuenta de servicio, clave SSH, archivo de entorno o política de reinicio. El instalador systemd aprovisiona esas piezas operativas, mantiene la configuración local intacta al reejecutarse e instala Rescue fuera del virtualenv del hub.

Las imágenes de contenedor no son un objetivo de despliegue oficial todavía. El hub necesita acceso a la red, una identidad SSH, state.db persistente y acceso a su inventario local; los operadores que lo empaqueten en un contenedor deben preservar estas propiedades por sí mismos.

Consulta docs/docker-packaging.md para los requisitos actuales y lo que una imagen oficial necesitaría garantizar antes de que pudiera ser recomendada.

Pruebas locales

Para una lista de verificación orientada a contribuyentes que cubra lint, pruebas unitarias, registro de herramientas, documentación generada, pruebas de humo del instalador y una ejecución manual de solo lectura, consulta docs/testing-local.md.

Para el resumen de migración de MCP 2026-07-28, matriz de compatibilidad y procedimiento de reversión, consulta docs/migration/mcp-2026-07-28-guide.md.

Antes de abrir un PR o publicar una rama, también puedes ejecutar las comprobaciones locales de preparación para el lanzamiento:

python3 scripts/check_repo_hygiene.py
python3 scripts/check_tool_annotations.py
python3 scripts/check_security_readiness.py

Para conectar la comprobación de preparación de seguridad en Git automáticamente al hacer push:

./scripts/install_pre_push_hook.sh

Arquitectura

server.py sigue siendo la raíz de composición del servidor MCP mientras que el código de dominio se mueve incrementalmente a tools/. La construcción de comandos SSH, las rutas de Cloudflare y la extracción de respuestas, los metadatos del protocolo DSM, el inventario y los constructores de playbooks ya están aislados. tools/registry.py asigna herramientas extraídas a un dominio; ese dominio se incluye en cada resumen de auditoría. La nueva lógica de protocolo debe residir en su módulo de dominio y no debe importar server.py.

Las futuras integraciones se priorizan en docs/integration-evaluation.md, incluyendo su alcance de mínimo privilegio y puertas de promoción.

Diagnósticos de rescate

mcp-hub-rescue es una CLI local de solo lectura diseñada para seguir funcionando cuando el servidor principal no puede importar o su virtualenv está roto. El instalador systemd lo copia a /opt/mcp-hub-rescue y lo ejecuta con el Python del sistema, fuera del proceso y virtualenv de MCP Hub.

sudo mcp-hub-rescue doctor
sudo mcp-hub-rescue status
sudo mcp-hub-rescue health
sudo mcp-hub-rescue logs --lines 50
sudo mcp-hub-rescue validate-config

Los resultados son JSON estructurado. Rescue nunca importa server.py, tools/*, MCP, o una integración opcional, y este límite se aplica mediante CI. Los comandos actuales solo observan y diagnostican; las operaciones de reinicio, reparación y reversión se agregarán por separado con confirmación y salvaguardas de último estado conocido bueno.

Configuración

Todos ignorados por git — cada uno tiene una plantilla .example rastreada:

Una entrada de host es mínima por diseño:

hosts:
  nas:
    hostname: nas.example.lan
    user: admin
    role: storage
    tags: [nas, backup]
    mac: "aa:bb:cc:dd:ee:01"   # optional, enables wake_host()

Las etiquetas son cómo te diriges a grupos: fleet_exec(tag="backup", command="df -h"). Para un inventario de dos hosts listo para copiar, comienza con docs/examples/hosts.minimal.yaml. El más grande hosts.example.yaml demuestra todas las opciones de host soportadas.

Combínalo con docs/examples/topology.guarded.yaml para mapear invitados de Proxmox, registrar trampas de direcciones obsoletas y mostrar infraestructura que no debe cambiarse a la ligera. Las entradas _do_not_touch son contexto operativo para el asistente, no un límite de control de acceso impuesto; usa perfiles de token y restricciones de host para la aplicación técnica.

Añade docs/examples/endpoints.minimal.yaml para monitorear servicios HTTP siempre activos e intermitentes. Llama a endpoints_health() para el conjunto regular, o endpoints_health(include_intermittent=true) para incluir servicios que pueden estar normalmente apagados. Las respuestas desde 200 hasta 399 se consideran saludables; las redirecciones no se siguen.

Los valores predeterminados completos, límites, configuraciones de integración y notas de manejo de secretos están en la referencia de variables de entorno.

Combina esos ejemplos rastreados con un PROJECT_INSTRUCTIONS.md privado y no rastreado para que tu asistente vea advertencias de topología, ventanas de mantenimiento, convenciones de nomenclatura y guías de "no tocar" que no deberían vivir en el repositorio.

Referencia de herramientas

Cada herramienta devuelve el mismo sobre de nivel superior:

{
  "ok": true,
  "data": {},
  "error": null,
  "duration_ms": 12,
  "host": "example",
  "request_id": "4d52b1f69b974b7784bf65dd",
  "tool": "system_info"
}

data contiene la carga útil específica de la herramienta. Los rechazos de seguridad y las excepciones controladas usan la misma forma con ok: false, haciendo que las llamadas encadenadas y la correlación de auditoría sean predecibles.

El envoltorio central de herramientas también limita el tamaño de la solicitud, las llamadas por token, las llamadas concurrentes por destino, los fallos repetidos de destino y la frecuencia de mutación. Los valores predeterminados están documentados en .env.example; los rechazos por límite usan el mismo sobre de respuesta y rastro de auditoría que cualquier otra llamada.

La referencia completa de herramientas generadas expande cada grupo en una table con la firma exacta de cada herramienta y su descripción orientada al modelo. CI la verifica contra las funciones registradas.

Los diagósticos guiados siempre se detienen después de la observación. Devuelven evidencia, evaluación y pasos siguientes sugeridos con correction_applied: false; check_backup_chain es una señal de frescura y almacenamiento, no una prueba de que una restauración tendrá éxito.

Seguridad

MCP Hub es un servicio de ejecución remota de código por diseño. Antes de exponerlo:

• Mantenga el enlace predeterminado 127.0.0.1, o póngalo detrás de un túnel con políticas de acceso.

• Configure MCP_AUTH_TOKEN — la ruta URL secreta es oscuridad, no autenticación.

• Deje MCP_READ_ONLY=true hasta que confíe en lo que su modelo hace con él.

• Mantenga habilitados los valores predeterminados del guardía de recursos, luego ajústelos a partir del tráfico de auditoría observado en lugar de deshabilitarlos.

• Asínele una clave SSH dedicada y un hosts.yaml mínimo.

Modelo de amenaza completo, guía de endurecimiento e inform de vulnerabilidades: SECURITY.md.

Para una lista de verificación local previa a la publicación y un gancho Git opcional que capture errores comunes de fugas de secretos antes del push, consulte scripts/check_security_readinses.py y scripts/install_pre_push_hook.sh.

Versionado

SemVer. Antes de la versión 1.0, los changes rompedores aumentan la minor — así que lea las notas de "Changed" y "Removed" antes de actualizar a una. _versión.py es la únca fuete de verdad; el servidor en ejecución lo informa a través de mcp-hub --versión, en el apretón de manos de MCP, y en mcp_health.

Cada lanzamiento está documentado en CHANGELOG.md, con los changes relevantes para la segurdad resaltados en su propia sección.

Contribuciones

Las incidencias y las solicitudes de incorporación de cambios son bienvenidas — especialmente informes de errores, nuevas integraciones y correcciones de documentación. Consulte CONTRIBUTING.md.

Licencia

MIT © wnx82