Homelab MCP

Servidores MCP para gestionar infraestructura de homelab a través de Claude Desktop. Monitoree contenedores Docker/Podman, modelos de IA Ollama, DNS Pi-hole, redes Unifi e inventario Ansible.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidores Homelab MCP

Servidores del Model Context Protocol (MCP) para gestionar infraestructura homelab a través de Claude Desktop.

Una colección de servidores del Model Context Protocol (MCP) para gestionar y monitorizar tu infraestructura homelab a través de Claude Desktop.

🔒 Aviso de Seguridad

⚠️ IMPORTANTE: Por favor, lee SECURITY.md antes de desplegar este proyecto.

Este proyecto interactúa con infraestructura crítica (APIs de Docker, DNS, dispositivos de red). Una configuración inadecuada puede exponer tu homelab a riesgos de seguridad.

Requisitos clave de seguridad:

NUNCA expongas las APIs de Docker/Podman a internet - Usa reglas de firewall para restringir el acceso
Mantén seguro el archivo .env - Contiene claves de API y nunca debe enviarse al repositorio
Usa claves de API únicas - Genera claves separadas para cada servicio
Revisa la seguridad de la red - Asegura una segmentación VLAN adecuada y reglas de firewall

Consulta SECURITY.md para obtener una guía completa de seguridad.

📚 Resumen de Documentación

Este proyecto incluye varios archivos de documentación para diferentes audiencias:

README.md (este archivo) - Guía de instalación, configuración y uso
MIGRATION_V3.md - Guía de migración para el servidor unificado v2.0
PROJECT_INSTRUCTIONS.md - Copia en las instrucciones del proyecto de Claude para contexto de IA
CLAUDE.md - Guía para desarrolladores, asistentes de IA y colaboradores
SECURITY.md - Políticas de seguridad y mejores prácticas
CONTRIBUTING.md - Cómo contribuir a este proyecto
CHANGELOG.md - Historial de versiones y cambios

👥 Para usuarios finales: Sigue este README + copia PROJECT_INSTRUCTIONS.md a Claude 🔄 ¿Migrando desde v1.x? Consulta MIGRATION_V3.md para la migración al servidor unificado 🤖 Para asistentes de IA: Lee CLAUDE.md para obtener el contexto completo de desarrollo 🔧 Para colaboradores: Comienza con CONTRIBUTING.md y CLAUDE.md

📖 Importante: Configura las Instrucciones del Proyecto de Claude

Después de configurar los servidores MCP, crea tus instrucciones personalizadas de proyecto:

Copia la plantilla de ejemplo:

# Windows
copy PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md

# Linux/Mac
cp PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md

Edita el archivo con los detalles reales de tu infraestructura:

PROJECT_INSTRUCTIONS.md (para las instrucciones del proyecto de Claude Desktop):
- Reemplaza las direcciones IP de ejemplo con tus direcciones de red reales
- Añade los nombres de host reales de tus servidores
- Personaliza con tus servicios y configuraciones específicos
- Mantén este archivo privado - contiene tu topología de red
CLAUDE_CUSTOM.md (para trabajo de desarrollo con IA - solo colaboradores):
- Actualiza las URLs del repositorio con tu repositorio real de GitHub
- Añade las URLs de tu espacio de trabajo de Notion si usas gestión de tareas
- Personaliza las referencias de infraestructura
- Mantén este archivo privado - contiene tus URLs y configuración específicas
Añade a Claude Desktop:
- Abre Claude Desktop
- Ve a la configuración de tu proyecto
- Copia el contenido de tu PROJECT_INSTRUCTIONS.md personalizado
- Pégalo en el campo "Instrucciones del proyecto"

Qué incluye:

Capacidades detalladas de los servidores MCP y patrones de uso
Visión general de la infraestructura y capacidades de monitorización
Comandos y herramientas específicos disponibles para cada servicio
Guía de resolución de problemas y desarrollo

Este README cubre la instalación y la configuración básica. Las instrucciones del proyecto proporcionan a Claude un contexto completo de uso.

🎯 Opciones de Despliegue

La versión 3.0.0 ofrece un despliegue flexible con dos modos y dos métodos:

Modos de Despliegue

Elige cómo se organizan tus servidores MCP:

1. Servidor Unificado (Recomendado)

Ejecuta todos los servidores MCP en un único proceso con herramientas con espacio de nombres (namespaced). Este es el enfoque recomendado para nuevas instalaciones y requerido para despliegues con Docker.

{
  "mcpServers": {
    "homelab-unified": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"]
    }
  }
}

Ventajas:

✅ Una única entrada de configuración
✅ Un solo proceso de Python para todos los servidores
✅ Registros (logs) más limpios (sin advertencias duplicadas)
✅ Todas las herramientas con espacio de nombres (p. ej., docker_get_containers, ping_ping_host)
✅ Requerido para despliegues con Docker
✅ Comprobaciones de salud integradas
✅ Contenerización lista para producción

2. Servidores Individuales (Legado, Totalmente Compatibles)

Ejecuta cada servidor MCP como un proceso separado. Este modo sigue siendo totalmente compatible para la retrocompatibilidad y solo está disponible con la instalación nativa de Python.

{
  "mcpServers": {
    "docker": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\docker_mcp_podman.py"]
    },
    "ollama": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\ollama_mcp.py"]
    }
  }
}

Ventajas:

✅ Control granular sobre cada servidor
✅ Puedes habilitar/deshabilitar servidores individualmente
✅ Nombres de herramientas originales (p. ej., get_docker_containers, ping_host)
✅ Compatible con versiones anteriores (v1.x)

Nota: Los nombres de las herramientas difieren entre modos. Consulta MIGRATION_V3.md para obtener instrucciones detalladas de migración y cambios en los nombres de las herramientas.

Métodos de Despliegue

Elige cómo instalar y ejecutar los servidores:

1. Contenedor Docker (Recomendado para Producción)

Imágenes preconstruidas disponibles en Docker Hub para un despliegue inmediato. Consulta 🐳 Despliegue con Docker para obtener instrucciones completas de configuración.

Inicio rápido:

docker pull bjeans/homelab-mcp:latest
docker-compose up -d

Ventajas:

✅ No se requiere configuración del entorno de Python
✅ Imágenes preconstruidas y probadas
✅ Actualizaciones automáticas con pulls de imágenes
✅ Soporte multiplataforma (amd64, arm64)
✅ Configuración simplificada
✅ Contenerización de grado de producción

Limitaciones:

Solo modo de servidor unificado
mcp-registry-inspector no disponible (obsoleto)

2. Instalación Nativa de Python (Desarrollo y Legado)

Instala las dependencias de Python directamente y ejecuta los servidores desde el código fuente. Consulta 📦 Instalación para obtener instrucciones completas de configuración.

Inicio rápido:

pip install -r requirements.txt
python homelab_unified_mcp.py

Ventajas:

✅ Acceso completo al código fuente
✅ Depuración y desarrollo fáciles
✅ Compatible con los modos de servidor unificado e individual
✅ Puede ejecutarse en cualquier plataforma compatible con Python

Requisitos:

Python 3.10+ con pip
Gestión manual de dependencias
Configuración del entorno mediante archivo .env

Guía de migración: Consulta MIGRATION_V3.md para obtener instrucciones detalladas sobre cómo cambiar entre modos o métodos.

⚡ Framework FastMCP (v3.0.0)

La versión 3.0.0 usa FastMCP: Un framework MCP moderno que simplifica la arquitectura del servidor al tiempo que añade soporte para múltiples mecanismos de transporte y anotaciones de herramientas.

¿Qué es FastMCP?

FastMCP es un framework ligero que:

✅ Reduce el código del servidor en un 38% (1.754 líneas eliminadas)
✅ Usa un patrón de decorador simple (@mcp.tool()) para definiciones de herramientas
✅ Incluye anotaciones completas de herramientas para sugerencias de comportamiento
✅ Añade soporte para transportes HTTP y SSE (además de stdio)
✅ Genera automáticamente esquemas a partir de sugerencias de tipo de Python
✅ Mejora el mantenimiento del código y facilita la incorporación de nuevos servidores

Las 39 herramientas ahora incluyen anotaciones MCP (readOnlyHint, idempotentHint, etc.) para ayudar a Claude a tomar decisiones informadas sobre el uso de las herramientas.

Opciones de Transporte

Los servidores FastMCP pueden operar utilizando diferentes mecanismos de transporte:

1. Entrada/Salida Estándar (stdio) - Predeterminado

El transporte MCP tradicional utilizado por Claude Desktop. Esta es la opción predeterminada y recomendada para la mayoría de los usuarios.

# Run with stdio (default)
python homelab_unified_mcp.py

# Or explicitly specify stdio transport
python homelab_unified_mcp.py --transport stdio

Cuándo usarlo:

Integración con Claude Desktop (modo predeterminado)
Caso de uso más común
No se necesita configuración adicional

2. Transporte HTTP

Ejecuta servidores MCP como servicios HTTP para escenarios de despliegue remoto o flexible.

# Start server with HTTP transport
python homelab_unified_mcp.py --transport http --host 0.0.0.0 --port 8000

# Test the HTTP endpoint
curl http://localhost:8000/tools

Cuándo usarlo:

Despliegue remoto de servidores
Integraciones basadas en web
Escenarios con múltiples clientes
Requisitos de equilibrio de carga

3. Transporte Server-Sent Events (SSE)

Protocolo basado en flujos (streams) para comunicación bidireccional en tiempo real.

# Start server with SSE transport
python homelab_unified_mcp.py --transport sse --host 0.0.0.0 --port 8000

# Connect via SSE client
curl http://localhost:8000/sse

Cuándo usarlo:

Aplicaciones de monitorización en tiempo real
Integraciones basadas en navegador
Arquitecturas basadas en eventos
Respuestas en streaming

Configurando Claude Desktop con FastMCP

Claude Desktop continúa usando el transporte stdio por defecto. No se requieren cambios de configuración:

{
  "mcpServers": {
    "homelab-unified": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"]
    }
  }
}

Migración desde v2.2.0

Si estás actualizando desde v2.2.0:

✅ Sin cambios disruptivos - Tu configuración existente sigue funcionando sin cambios
✅ Misma funcionalidad - Los 7 servidores y todas las herramientas permanecen idénticos
✅ Código más limpio - La refactorización interna produce los mismos resultados
✅ Nuevas opciones - Transportes HTTP/SSE opcionales disponibles si es necesario

No se requiere ninguna acción: solo actualiza y reinicia Claude Desktop.

🚀 Inicio Rápido

1. Clona el repositorio

git clone https://github.com/bjeans/homelab-mcp
cd homelab-mcp

2. Instala las comprobaciones de seguridad (recomendado)

# Install pre-push git hook for automatic security validation
python helpers/install_git_hook.py

3. Configura los archivos de configuración

Variables de entorno:

# Windows
copy .env.example .env

# Linux/Mac
cp .env.example .env

Edita .env con tus valores reales:

# Windows
notepad .env

# Linux/Mac
nano .env

Inventario de Ansible (si se usa):

# Windows
copy ansible_hosts.example.yml ansible_hosts.yml

# Linux/Mac
cp ansible_hosts.example.yml ansible_hosts.yml

Edítalo con los detalles de tu infraestructura.

Instrucciones del proyecto:

# Windows
copy PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md

# Linux/Mac
cp PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md

Personalízalo con tu topología de red y tus servidores.

Personalizaciones de la guía de desarrollo de IA (opcional):

# Windows
copy CLAUDE_CUSTOM.example.md CLAUDE_CUSTOM.md

# Linux/Mac
cp CLAUDE_CUSTOM.example.md CLAUDE_CUSTOM.md

Personalízalo con los nombres reales de tus servidores y los detalles de tu infraestructura. Este archivo está en gitignore y permite que Claude comprenda tu configuración homelab específica. Consulta CLAUDE.md para obtener más información sobre las personalizaciones locales.

4. Instala las dependencias de Python

pip install -r requirements.txt

5. Añade a la configuración de Claude Desktop

Ubicación del archivo de configuración:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Opción A: Servidor Unificado (Recomendado)

Una única entrada para todos los servidores homelab:

{
  "mcpServers": {
    "homelab-unified": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    }
  }
}

Nota: El servidor unificado incluye 7 servidores MCP: Ansible, Docker/Podman, Ollama, Pi-hole, Unifi, UPS y Ping. El obsoleto mcp-registry-inspector no está incluido.

Opción B: Servidores Individuales (Legado)

Entrada separada para cada servidor:

{
  "mcpServers": {
    "docker": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\docker_mcp_podman.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    },
    "ollama": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\ollama_mcp.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    },
    "pihole": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\pihole_mcp.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    },
    "unifi": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\unifi_mcp_optimized.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    },
    "ping": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\ping_mcp_server.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    },
    "ups-monitor": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\ups_mcp_server.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    }
  }
}

Nota: Los nombres de las herramientas difieren entre modos. Consulta MIGRATION_V3.md para más detalles. El obsoleto mcp-registry-inspector ha sido eliminado de este ejemplo. La integración del servidor MCP de Ansible se sigue en #39.

6. Reinicia Claude Desktop

7. Añade las instrucciones del proyecto a Claude

Copia el contenido de tu PROJECT_INSTRUCTIONS.md personalizado
Pégalo en el campo "Instrucciones del proyecto" de tu proyecto de Claude
Esto le da a Claude un contexto completo sobre tus capacidades MCP

🐳 Despliegue con Docker (Alternativa)

Ejecuta los servidores MCP en contenedores Docker para una distribución, aislamiento y despliegue en producción más fáciles.

Docker Hub: bjeans/homelab-mcp

Inicio Rápido con Docker Hub (Lo más fácil)

Las imágenes preconstruidas se publican automáticamente en Docker Hub con soporte multiplataforma (amd64/arm64):

# Pull the latest image
docker pull bjeans/homelab-mcp:latest

# Run with your Ansible inventory
docker run -d \
  --name homelab-mcp \
  --network host \
  -v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
  bjeans/homelab-mcp:latest

# Or use a specific commit
docker pull bjeans/homelab-mcp:main-17bae01

Disponible en Docker Hub: https://hub.docker.com/r/bjeans/homelab-mcp/tags

Etiquetas (tags) disponibles actualmente:

latest - Última versión estable de la rama main (recomendada)
edge - Última compilación de desarrollo de la rama main
main-<git-sha> - Compilaciones de commits específicos para trazabilidad (p. ej., main-17bae01)

Etiquetas de versión semántica (disponibles después del lanzamiento):

Etiquetas de versión como 2.2.0, 2.2, 2 se crearán cuando se publique el lanzamiento de Git v2.2.0
Hasta entonces, usa latest para la compilación estable más reciente

Soporte multiplataforma:

linux/amd64 - Servidores y estaciones de trabajo x86_64
linux/arm64 - Raspberry Pi, sistemas basados en ARM

Compilar desde el Código Fuente (Avanzado)

Compila la imagen localmente si necesitas personalizarla:

# Pull the pre-built image from Docker Hub (recommended)
docker pull bjeans/homelab-mcp:latest

# Run with Docker Compose (recommended for production)
docker-compose up -d

# Or run unified server directly
docker run -d \
  --name homelab-mcp \
  --network host \
  -v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
  bjeans/homelab-mcp:latest

Compilación desde el código fuente (opcional):

# Clone and navigate to repository
git clone https://github.com/bjeans/homelab-mcp
cd homelab-mcp

# Build the image locally
docker build -t homelab-mcp:latest .

Características de Docker

2.0.0 Mejoras de Docker:

✅ Servidor MCP unificado como entrypoint predeterminado (los 7 servidores en un contenedor)
✅ Detección automática de modo unificado (no se necesita ENABLED_SERVERS)
✅ Health checks integrados (HEALTHCHECK configurado)
✅ Seguridad de usuario no root (mcpuser UID 1000)
✅ Manejo adecuado de señales y apagado limpio
✅ Caché de capas optimizada para reconstrucciones más rápidas
✅ Dependencias del sistema incluidas (iputils-ping para soporte multiplataforma)

Métodos de Configuración

Método 1: Inventario de Ansible (Recomendado)

# Create your ansible_hosts.yml with infrastructure details
# Then mount as volume:

docker run -d \
  --name homelab-mcp \
  --network host \
  -v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
  bjeans/homelab-mcp:latest

Método 2: Variables de Entorno (Listo para Marketplace)

docker run -d \
  --name homelab-mcp \
  --network host \
  -e DOCKER_SERVER1_ENDPOINT=192.168.1.100:2375 \
  -e DOCKER_SERVER1_NAME=Local-Docker \
  -e OLLAMA_SERVER1_ENDPOINT=192.168.1.100:11434 \
  bjeans/homelab-mcp:latest

Modo Legado: Servidores Individuales (Docker)

Para compatibilidad hacia atrás, aún puedes ejecutar servidores individuales configurando ENABLED_SERVERS:

docker run -d \
  --name homelab-mcp-docker \
  --network host \
  -e ENABLED_SERVERS=docker \
  -v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
  bjeans/homelab-mcp:latest

Servidores Disponibles

Modo Unificado (Predeterminado):

✅ Los 7 servidores en un solo proceso: Ansible, Docker, Ping, Ollama, Pi-hole, Unifi, UPS
✅ Herramientas con espacio de nombres (ej., ansible_get_all_hosts, docker_get_containers, ups_get_ups_status)
✅ Entrada de configuración única
✅ Health checks integrados

Modo Legado (Configurar ENABLED_SERVERS):

✅ ansible - Consultas de inventario de Ansible
✅ docker - Gestión de contenedores Docker/Podman
✅ ping - Utilidades de ping de red
✅ ollama - Gestión de modelos de IA de Ollama
✅ pihole - Estadísticas de DNS de Pi-hole
✅ unifi - Monitoreo de dispositivos de red Unifi
✅ ups - Monitoreo de energía UPS/NUT

Configuración de Docker

Dos métodos de configuración soportados:

Inventario de Ansible (Recomendado) - Montar como volumen
Variables de Entorno - Pasar mediante banderas -e de Docker

Consulta DOCKER.md para una guía completa de despliegue de Docker que incluye:

Instrucciones detalladas de configuración
Opciones de configuración de red
Mejores prácticas de seguridad
Integración con Claude Desktop
Solución de problemas comunes

Integración con Claude Desktop

Modo Unificado (Recomendado):

{
  "mcpServers": {
    "homelab-unified": {
      "command": "docker",
      "args": ["exec", "-i", "homelab-mcp", "python", "homelab_unified_mcp.py"]
    }
  }
}

Modo Legado (Servidores Individuales):

{
  "mcpServers": {
    "homelab-docker": {
      "command": "docker",
      "args": ["exec", "-i", "homelab-mcp-docker", "python", "docker_mcp_podman.py"]
    },
    "homelab-ping": {
      "command": "docker",
      "args": ["exec", "-i", "homelab-mcp", "python", "ping_mcp_server.py"]
    }
  }
}

Importante: Usa docker exec -i (no -it) para una comunicación adecuada de MCP stdio.

Pruebas de Contenedores Docker

Prueba rápida de verificación (usando variables de entorno - listo para marketplace):

# Test Unified Server
docker run --rm --network host \
    -e DOCKER_SERVER1_ENDPOINT=localhost:2375 \
    -e OLLAMA_SERVER1_ENDPOINT=localhost:11434 \
    bjeans/homelab-mcp:latest

# Test Individual Server (legacy)
docker run --rm --network host \
    -e ENABLED_SERVERS=ping \
    bjeans/homelab-mcp:latest

Pruebas con Docker Compose:

docker-compose up -d
docker-compose logs -f

Para una guía completa de despliegue de Docker, consulta DOCKER.md.

📦 Servidores MCP Disponibles

✨ Enums Dinámicos de Parámetros de Herramientas (Nuevo en v2.1.0)

Cuando configuras el inventario de Ansible, Claude Desktop mostrará automáticamente tus opciones de infraestructura en menús desplegables. ¡No más adivinar nombres de hosts o grupos!

Qué se autocompleta:

Herramientas de Ping - Tus grupos de Ansible aparecen en menús desplegables
Herramientas de Docker - Tus hosts de Docker/Podman se muestran en menús desplegables
Herramientas de Ollama - Los nombres de host de tu servidor Ollama están disponibles para selección
Herramientas de UPS - Los nombres de host de tu servidor NUT se muestran en menús desplegables

Cómo funciona:

Configura ANSIBLE_INVENTORY_PATH en tu archivo .env
Reinicia Claude Desktop (requerido - los enums se cargan al inicio)
Al usar herramientas, Claude muestra tu infraestructura real en menús desplegables en lugar de requerir entrada manual

Notas Importantes:

Reinicio Requerido: Los cambios en el inventario de Ansible requieren reiniciar Claude Desktop para actualizar las opciones desplegables
Rendimiento: Los enums se generan una vez al inicio - impacto mínimo incluso con inventarios grandes (100+ hosts)
Degradación Elegante: Si no hay inventario de Ansible configurado, las herramientas aún funcionan - solo que no verás sugerencias desplegables

Ejemplo antes/después:

Antes: "¿Qué grupo debería hacer ping?" → El usuario escribe manualmente "webservers" (o adivina) Después: "¿Qué grupo debería hacer ping?" → El usuario selecciona del menú desplegable: all, docker_hosts, webservers, databases, etc.

Solución de Problemas:

¿No aparecen los menús desplegables? Verifica que ANSIBLE_INVENTORY_PATH esté configurado y reinicia Claude Desktop
¿Aparecen opciones incorrectas? Verifica que tu inventario de Ansible esté actualizado y reinicia Claude Desktop
¿Problemas de rendimiento? La generación de enums ocurre una vez al inicio - si es lento, verifica el tamaño del archivo de inventario y la instalación de Ansible

Inspector del Registro MCP (⚠️ OBSOLETO)

Aviso de Obsolescencia (v2.3.0): Esta herramienta está obsoleta. Claude Desktop ahora tiene acceso nativo al sistema de archivos, haciendo innecesario este servidor MCP. Simplemente puedes pedirle a Claude que lea tus archivos de servidor MCP o configuración directamente.

Reemplazo: Usa el acceso de archivos integrado de Claude:

"Lee mi archivo claude_desktop_config.json"
"Muéstrame el código fuente de docker_mcp_podman.py"
"Lista todos los archivos .py en este directorio"

Para usuarios con configuraciones existentes: Este servidor seguirá funcionando pero no recibirá actualizaciones. Será eliminado de la documentación en v3.0.0. Considera eliminarlo de tu claude_desktop_config.json.

Configuración Legada (solo para referencia)

Herramientas:

get_claude_config - Ver configuración MCP de Claude Desktop
list_mcp_servers - Listar todos los servidores MCP registrados
list_mcp_directory - Explorar el directorio de desarrollo MCP
read_mcp_file - Leer código fuente del servidor MCP
write_mcp_file - Escribir/actualizar archivos del servidor MCP
search_mcp_files - Buscar archivos por nombre

Configuración:

MCP_DIRECTORY=/path/to/your/Homelab-MCP
CLAUDE_CONFIG_PATH=/path/to/claude_desktop_config.json  # Optional

Administrador de Contenedores Docker/Podman

Gestiona contenedores Docker y Podman en múltiples hosts.

🔒 Advertencia de Seguridad: Las APIs de Docker/Podman típicamente usan HTTP sin cifrar y sin autenticación. Consulta SECURITY.md para la configuración de firewall requerida.

Herramientas:

Modo servidor individual:

get_docker_containers - Obtener contenedores en un host específico
get_all_containers - Obtener todos los contenedores en todos los hosts
get_container_stats - Obtener estadísticas de CPU y memoria
check_container - Verificar si un contenedor específico está en ejecución
find_containers_by_label - Encontrar contenedores por etiqueta
get_container_labels - Obtener todas las etiquetas de un contenedor

Modo servidor unificado (con espacio de nombres):

docker_get_containers - Obtener contenedores en un host específico
docker_get_all_containers - Obtener todos los contenedores en todos los hosts
docker_get_container_stats - Obtener estadísticas de CPU y memoria
docker_check_container - Verificar si un contenedor específico está en ejecución
docker_find_containers_by_label - Encontrar contenedores por etiqueta
docker_get_container_labels - Obtener todas las etiquetas de un contenedor

Opciones de Configuración:

Opción 1: Usando Inventario de Ansible (Recomendado)

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml

# Ansible inventory group names (default: docker_hosts, podman_hosts)
# Change these if you use different group names in your ansible_hosts.yml
DOCKER_ANSIBLE_GROUP=docker_hosts
PODMAN_ANSIBLE_GROUP=podman_hosts

Opción 2: Usando Variables de Entorno

DOCKER_SERVER1_ENDPOINT=192.168.1.100:2375
DOCKER_SERVER2_ENDPOINT=192.168.1.101:2375
PODMAN_SERVER1_ENDPOINT=192.168.1.102:8080

Administrador de Modelos de IA Ollama

Monitorea y gestiona instancias de modelos de IA Ollama en tu homelab, además de verificar tu proxy LiteLLM para acceso API unificado.

Qué Incluye

Monitoreo de Ollama:

Rastrear múltiples instancias de Ollama en diferentes hosts
Ver modelos disponibles y sus tamaños
Verificar la salud y disponibilidad de las instancias

Integración con Proxy LiteLLM:

LiteLLM proporciona una API unificada compatible con OpenAI en todas tus instancias de Ollama
Habilita balanceo de carga y conmutación por error entre múltiples servidores Ollama
Te permite usar bibliotecas de cliente de OpenAI con tus modelos locales
El servidor MCP puede verificar que tu proxy LiteLLM esté en línea y respondiendo

¿Por qué usar LiteLLM?

Balanceo de Carga: Distribuye automáticamente las solicitudes entre múltiples instancias de Ollama
Conmutación por Error: Si un servidor Ollama está caído, las solicitudes se enrutan a servidores saludables
Compatibilidad con OpenAI: Usa cualquier SDK/biblioteca de OpenAI con tus modelos locales
Acceso Centralizado: Un solo endpoint (ej., http://192.0.2.10:4000) para todos los modelos
Seguimiento de Uso: Monitorea qué modelos se usan más

Herramientas:

get_ollama_status - Verificar el estado de todas las instancias de Ollama y conteos de modelos
get_ollama_models - Obtener lista detallada de modelos para un host específico
get_litellm_status - Verificar que el proxy LiteLLM esté en línea y respondiendo

Opciones de Configuración:

Opción 1: Usando Inventario de Ansible (Recomendado)

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
OLLAMA_PORT=11434  # Default Ollama port

# Ansible inventory group name (default: ollama_servers)
# Change this if you use a different group name in your ansible_hosts.yml
OLLAMA_INVENTORY_GROUP=ollama_servers

# LiteLLM Configuration
LITELLM_HOST=192.168.1.100  # Host running LiteLLM proxy
LITELLM_PORT=4000           # LiteLLM proxy port (default: 4000)

Opción 2: Usando Variables de Entorno

# Ollama Instances
OLLAMA_SERVER1=192.168.1.100
OLLAMA_SERVER2=192.168.1.101
OLLAMA_WORKSTATION=192.168.1.150

# LiteLLM Proxy
LITELLM_HOST=192.168.1.100
LITELLM_PORT=4000

Configuración de LiteLLM (Opcional):

Si deseas usar LiteLLM para acceso unificado a tus instancias de Ollama:

Instala LiteLLM en uno de tus servidores:
```
pip install litellm[proxy]
```

Crea la configuración (litellm_config.yaml):

model_list:
  - model_name: llama3.2
    litellm_params:
      model: ollama/llama3.2
      api_base: http://server1:11434
  - model_name: llama3.2
    litellm_params:
      model: ollama/llama3.2
      api_base: http://server2:11434

router_settings:
  routing_strategy: usage-based-routing

Inicia el proxy LiteLLM:

litellm --config litellm_config.yaml --port 4000

Usa la herramienta MCP para verificar que esté en ejecución:
- En Claude: "Verifica el estado de mi proxy LiteLLM"

Ejemplos de Uso:

"¿Qué instancias de Ollama tengo en ejecución?"
"Muéstrame todos los modelos en mi Dell-Server"
"¿Está en línea mi proxy LiteLLM?"
"¿Cuántos modelos están disponibles en todos los servidores?"

Administrador de DNS Pi-hole

Monitorea estadísticas y estado de DNS de Pi-hole.

🔒 Nota de Seguridad: Almacena las claves API de Pi-hole de forma segura en el archivo .env. Genera claves únicas por instancia.

Herramientas:

get_pihole_stats - Obtener estadísticas de DNS de todas las instancias de Pi-hole
get_pihole_status - Verificar qué instancias de Pi-hole están en línea

Opciones de Configuración:

Opción 1: Usando Inventario de Ansible (Recomendado)

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml

# Ansible inventory group name (default: PiHole)
# Change this if you use a different group name in your ansible_hosts.yml
PIHOLE_ANSIBLE_GROUP=PiHole

# API keys still required in .env:
PIHOLE_API_KEY_SERVER1=your-api-key-here
PIHOLE_API_KEY_SERVER2=your-api-key-here

Opción 2: Usando Variables de Entorno

PIHOLE_API_KEY_SERVER1=your-api-key
PIHOLE_API_KEY_SERVER2=your-api-key
PIHOLE_SERVER1_HOST=pihole1.local
PIHOLE_SERVER1_PORT=80
PIHOLE_SERVER2_HOST=pihole2.local
PIHOLE_SERVER2_PORT=8053

Cómo Obtener Claves API de Pi-hole:

Interfaz Web: Configuración → API → Mostrar Token API
O genera una nueva: pihole -a -p en el servidor Pi-hole

Monitor de Red Unifi

Monitorea la infraestructura de red Unifi y clientes con caché para rendimiento.

🔒 Nota de Seguridad: Usa una clave API dedicada con los permisos mínimos requeridos.

Herramientas:

get_network_devices - Obtener todos los dispositivos de red (switches, APs, gateways)
get_network_clients - Obtener todos los clientes de red activos
get_network_summary - Obtener resumen de la red
refresh_network_data - Forzar actualización desde el controlador (omite la caché)

Configuración:

UNIFI_API_KEY=your-unifi-api-key
UNIFI_HOST=192.168.1.1

Nota: Los datos se almacenan en caché durante 5 minutos para mejorar el rendimiento. Usa refresh_network_data para forzar la actualización.

Inspector de Inventario de Ansible

Consulta información del inventario de Ansible (solo lectura). Disponible en modos unificado y autónomo.

Herramientas del Modo Unificado (con prefijo ansible_):

ansible_get_all_hosts - Obtener todos los hosts en el inventario
ansible_get_all_groups - Obtener todos los grupos
ansible_get_host_details - Obtener información detallada del host
ansible_get_group_details - Obtener información detallada del grupo
ansible_get_hosts_by_group - Obtener hosts en un grupo específico
ansible_search_hosts - Buscar hosts por patrón o variable
ansible_get_inventory_summary - Resumen general del inventario
ansible_reload_inventory - Recargar inventario desde el disco

Herramientas del Modo Autónomo (sin prefijo):

get_all_hosts - Obtener todos los hosts en el inventario
get_all_groups - Obtener todos los grupos
get_host_details - Obtener información detallada del host
get_group_details - Obtener información detallada del grupo
get_hosts_by_group - Obtener hosts en un grupo específico
search_hosts - Buscar hosts por patrón o variable
get_inventory_summary - Resumen general del inventario
reload_inventory - Recargar inventario desde el disco

Configuración:

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml

Despliegue:

✅ Disponible en modo servidor unificado
✅ Disponible en despliegues Docker
✅ Disponible en modo autónomo: python ansible_mcp_server.py

Monitor de Conectividad de Red Ping

Prueba la conectividad de red y la disponibilidad de hosts usando ping ICMP en tu infraestructura.

¿Por qué usar esto?

Verificaciones rápidas de salud durante interrupciones o después de eventos de energía
Verifica qué hosts son alcanzables antes de consultar MCPs específicos de servicios
Herramienta simple de solución de problemas para identificar problemas de red
Pruebas de conectividad de referencia para tu infraestructura

Herramientas:

ping_host - Hacer ping a un solo host por nombre (resuelto desde el inventario de Ansible)
ping_group - Hacer ping a todos los hosts en un grupo de Ansible concurrentemente
ping_all - Hacer ping a todos los hosts de infraestructura concurrentemente
list_groups - Listar grupos de Ansible disponibles para operaciones de ping

Características:

✅ Compatibilidad multiplataforma - Funciona en Windows, Linux y macOS
✅ Integración con Ansible - Resuelve automáticamente nombres de host/IPs desde el inventario
✅ Pings concurrentes - Prueba múltiples hosts simultáneamente para obtener resultados más rápidos
✅ Estadísticas detalladas - RTT mín/prom/máx, porcentaje de pérdida de paquetes
✅ Personalizable - Configura tiempo de espera y número de paquetes
✅ Sin dependencias - Utiliza el comando ping del sistema (no se necesitan librerías adicionales)

Configuración:

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
# No additional API keys required!

Ejemplo de uso:

"Hacer ping a server1.example.local"
"Verificar conectividad con todos los servidores Pi-hole"
"Hacer ping a todos los hosts Ubuntu_Server"
"Probar conectividad con toda la infraestructura"
"¿Qué grupos puedo usar para hacer ping?"

Cuándo usar:

Después de cortes de energía - Identifica rápidamente qué hosts volvieron a estar en línea
Antes de verificaciones de servicios - Verifica que el host sea accesible antes de comprobar servicios específicos
Solución de problemas de red - Aísla problemas de conectividad de problemas de servicios
Monitoreo de salud - Verificaciones regulares para asegurar la disponibilidad de la infraestructura

Monitoreo de UPS (Network UPS Tools)

Monitorea dispositivos UPS (Sistema de Alimentación Ininterrumpida) en tu infraestructura utilizando el protocolo Network UPS Tools (NUT).

¿Por qué usar esto?

Visibilidad en tiempo real del estado de la infraestructura eléctrica
Alertas proactivas antes del agotamiento de la batería durante cortes
Monitoreo de múltiples dispositivos UPS en diferentes hosts
Seguimiento de la salud de la batería y estimaciones de tiempo de funcionamiento
Esencial para la planificación de infraestructura crítica

Herramientas:

get_ups_status - Verifica el estado de todos los dispositivos UPS en todos los servidores NUT
get_ups_details - Obtiene información detallada para un dispositivo UPS específico
get_battery_runtime - Obtiene estimaciones de tiempo de funcionamiento de la batería para todos los dispositivos UPS
get_power_events - Verifica eventos de energía recientes (con batería, batería baja)
list_ups_devices - Lista todos los dispositivos UPS configurados en el inventario
reload_inventory - Recarga el inventario de Ansible después de cambios

Características:

✅ Soporte de protocolo NUT - Utiliza el protocolo estándar de Network UPS Tools (puerto 3493)
✅ Integración con Ansible - Descubre automáticamente UPS desde el inventario
✅ Múltiples UPS por host - Soporte para servidores con múltiples dispositivos UPS
✅ Monitoreo de batería - Seguimiento del nivel de carga, tiempo de funcionamiento restante, porcentaje de carga
✅ Detección de eventos de energía - Identifica cuando el UPS cambia a batería o batería baja
✅ Multiplataforma - Funciona con cualquier UPS compatible con NUT (TrippLite, APC, CyberPower, etc.)
✅ Autenticación flexible - Autenticación opcional con nombre de usuario/contraseña

Configuración:

Opción 1: Usando el Inventario de Ansible (Recomendado)

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml

# Default NUT port (optional, defaults to 3493)
NUT_PORT=3493

# NUT authentication (optional - only if your NUT server requires it)
NUT_USERNAME=monuser
NUT_PASSWORD=secret

Ejemplo de inventario de Ansible:

nut_servers:
  hosts:
    dell-server.example.local:
      ansible_host: 192.168.1.100
      nut_port: 3493
      ups_devices:
        - name: tripplite
          description: "TrippLite SMART1500LCDXL"

Opción 2: Usando Variables de Entorno

NUT_PORT=3493
NUT_USERNAME=monuser
NUT_PASSWORD=secret

Requisitos previos:

Instalar NUT en servidores con dispositivos UPS:

# Debian/Ubuntu
sudo apt install nut nut-client nut-server

# RHEL/Rocky/CentOS
sudo dnf install nut nut-client

Configurar el daemon de NUT (/etc/nut/ups.conf):

[tripplite]
    driver = usbhid-ups
    port = auto
    desc = "TrippLite SMART1500LCDXL"

Habilitar monitoreo de red (/etc/nut/upsd.conf):
```
LISTEN 0.0.0.0 3493
```

Configurar acceso (/etc/nut/upsd.users):

[monuser]
    password = secret
    upsmon master

Iniciar los servicios de NUT:

sudo systemctl enable nut-server nut-client
sudo systemctl start nut-server nut-client

Ejemplo de uso:

"¿Cuál es el estado de todos mis dispositivos UPS?"
"Muéstrame el tiempo de funcionamiento de la batería para el UPS del servidor Dell"
"Verifica si hay eventos de energía"
"Obtén información detallada sobre el UPS TrippLite"
"Lista todos los dispositivos UPS configurados"

Cuándo usar:

Después de fluctuaciones de energía - Verifica que los dispositivos UPS manejaron el evento correctamente
Antes de mantenimiento - Verifica los niveles de batería y el tiempo de funcionamiento estimado
Monitoreo regular - Seguimiento de la salud del UPS y la condición de la batería
Planificación de capacidad - Comprende cuánto tiempo pueden funcionar los sistemas con batería

Códigos de estado comunes de UPS:

OL - En línea (operación normal, energía de CA presente)
OB - Con batería (corte de energía, funcionando con batería)
LB - Batería baja (batería críticamente baja, apagado inminente)
CHRG - Cargando (la batería se está cargando)
RB - Reemplazar batería (la batería necesita ser reemplazada)

🔒 Seguridad

Verificaciones de seguridad automatizadas

Este proyecto incluye validación de seguridad automatizada para prevenir la exposición accidental de datos sensibles:

Instala el hook de git pre-push (recomendado):

# From project root
python helpers/install_git_hook.py

Qué hace:

Ejecuta automáticamente helpers/pre_publish_check.py antes de cada git push
Bloquea pushes que contengan posibles secretos o datos sensibles
Protege contra la confirmación accidental de claves API, contraseñas o información personal

Verificación de seguridad manual:

# Run security validation manually
python helpers/pre_publish_check.py

Omitir la verificación de seguridad (usar con extrema precaución):

# Only when absolutely necessary
git push --no-verify

Prácticas críticas de seguridad

Archivos de configuración:

✅ HACER usar .env.example como plantilla
✅ HACER mantener permisos de archivo restrictivos para .env (chmod 600 en Linux/Mac)
❌ NUNCA confirmar .env en el control de versiones
❌ NUNCA confirmar ansible_hosts.yml con infraestructura real
❌ NUNCA confirmar PROJECT_INSTRUCTIONS.md con topología de red real

Seguridad de API:

✅ HACER usar claves API únicas para cada servicio
✅ HACER rotar las claves API regularmente (se recomienda cada 90 días)
✅ HACER usar claves fuertes generadas aleatoriamente (32+ caracteres)
❌ NUNCA exponer APIs de Docker/Podman a internet
❌ NUNCA reutilizar claves API entre entornos

Seguridad de red:

✅ HACER usar reglas de firewall para restringir el acceso a la API
✅ HACER implementar segmentación VLAN
✅ HACER habilitar TLS/HTTPS donde sea posible
❌ NUNCA exponer interfaces de gestión públicamente

Para obtener una guía de seguridad detallada, consulta SECURITY.md

📋 Requisitos

Requisitos del sistema

Python: 3.10 o superior
Claude Desktop: Se recomienda la última versión
Acceso a la red: Conectividad con los servicios del homelab

Dependencias de Python

Instala mediante requirements.txt:

pip install -r requirements.txt

Dependencias principales:

mcp - SDK del Protocolo de Contexto de Modelo
aiohttp - Cliente HTTP asíncrono
pyyaml - Análisis YAML para el inventario de Ansible

Requisitos de servicios

Docker/Podman: API habilitada en los hosts monitoreados
Pi-hole: v6+ con API habilitada
Unifi Controller: Acceso a la API habilitado
Ollama: Instancias en ejecución con API accesible
NUT (Network UPS Tools): Instalado y configurado en hosts con dispositivos UPS
Ansible: Archivo de inventario (opcional pero recomendado)

💻 Compatibilidad

Plataformas probadas

Desarrollado y probado en:

SO: Windows 11
Claude Desktop: Versión 0.13.64
Python: Versión 3.13.8

Notas multiplataforma

Windows: Totalmente probado y compatible ✅ macOS: Debería funcionar pero no probado ⚠️ Linux: Debería funcionar pero no probado ⚠️

Diferencias conocidas entre plataformas:

Las rutas de archivo en la documentación están en estilo Windows
Los separadores de ruta pueden necesitar ajustes para sistemas Unix
Los permisos de archivo .env deben establecerse en Unix (chmod 600 .env)

¡Se aceptan contribuciones para otras plataformas!

🛠️ Desarrollo

📖 ¿Primera vez contribuyendo? Lee CLAUDE.md para obtener una guía completa de desarrollo, incluyendo patrones de arquitectura, requisitos de seguridad y flujos de trabajo para asistentes de IA.

Primeros pasos

Instala el hook de seguridad de git (requerido para contribuyentes):
```
python helpers/install_git_hook.py
```

Configura el entorno de desarrollo:

pip install -r requirements.txt
cp .env.example .env
# Edit .env with your test values

Pruebas locales de servidores MCP

Antes de enviar un PR, prueba tus cambios en el servidor MCP localmente usando la herramienta MCP Inspector.

Inicio rápido:

# MCP Inspector is an optional Node.js tool for interactive testing
# Option 1: Use npx (no installation needed - recommended)
npx @modelcontextprotocol/inspector uv --directory . run <server>_mcp.py

# Option 2: Install globally first (one-time setup)
npm install -g @modelcontextprotocol/inspector
# Then run: mcp-inspector uv --directory . run <server>_mcp.py

Esto abre un depurador basado en web en http://localhost:5173 donde puedes:

Ver todas las herramientas disponibles para el servidor MCP
Probar cada herramienta con argumentos de ejemplo
Verificar que las respuestas estén formateadas correctamente
Depurar problemas antes de enviar PRs

Para instrucciones detalladas de prueba, consulta la sección Pruebas locales de servidores MCP en CONTRIBUTING.md.

Scripts auxiliares

El directorio helpers/ contiene scripts de utilidad para desarrollo e implementación:

install_git_hook.py - Instala el hook de git pre-push para verificaciones de seguridad automáticas
pre_publish_check.py - Script de validación de seguridad (se ejecuta automáticamente mediante el hook de git)

Uso:

# Install security git hook
python helpers/install_git_hook.py

# Run security check manually  
python helpers/pre_publish_check.py

Estructura del proyecto

Homelab-MCP/
├── MCP Servers (7 production servers)
│   ├── ansible_mcp_server.py      # Ansible inventory queries (integration in progress)
│   ├── docker_mcp_podman.py       # Docker/Podman container monitoring
│   ├── ollama_mcp.py              # Ollama AI model management
│   ├── pihole_mcp.py              # Pi-hole DNS monitoring
│   ├── ping_mcp_server.py         # Network connectivity testing
│   ├── unifi_mcp_optimized.py     # Unifi network device monitoring
│   └── ups_mcp_server.py          # UPS/NUT monitoring
│
├── Unified Server & Core Modules
│   ├── homelab_unified_mcp.py     # Combines all servers (Docker entrypoint)
│   ├── mcp_config_loader.py       # Secure environment variable loading
│   ├── mcp_error_handler.py       # Centralized error handling
│   └── ansible_config_manager.py  # Ansible inventory + enum generation
│
├── Utilities & Deprecated Tools
│   ├── unifi_exporter.py          # Unifi data export utility
│   └── mcp_registry_inspector.py  # MCP file management (⚠️ DEPRECATED v2.3.0)
│
├── Configuration & Examples
│   ├── .env.example               # Configuration template (gitignored)
│   ├── ansible_hosts.example.yml  # Ansible inventory example (gitignored)
│   ├── PROJECT_INSTRUCTIONS.example.md # AI assistant guide template
│   └── CLAUDE_CUSTOM.example.md   # Local customization template (gitignored)
│
├── Documentation
│   ├── README.md                  # This file - user documentation
│   ├── CLAUDE.md                  # AI assistant development guide
│   ├── SECURITY.md                # Security guidelines
│   ├── CONTRIBUTING.md            # Contribution guide
│   ├── CHANGELOG.md               # Version history
│   ├── MIGRATION_V3.md               # Version migration guide
│   ├── CONTEXT_AWARE_SECURITY.md  # Security scanning docs
│   ├── CI_CD_CHECKS.md            # CI/CD automation docs
│   └── LICENSE                    # MIT License
│
├── Docker Deployment
│   ├── Dockerfile                 # Container build configuration
│   ├── docker-compose.yml         # Container orchestration (uses bjeans/homelab-mcp:latest)
│   └── docker-entrypoint.sh       # Container startup script
│
├── Development Tools
│   ├── helpers/
│   │   ├── install_git_hook.py    # Git pre-push hook installer
│   │   ├── pre_publish_check.py   # Security validation
│   │   ├── run_checks.py          # CI/CD check runner
│   │   └── requirements-dev.txt   # Development dependencies
│   ├── requirements.txt           # Production Python dependencies
│   └── .gitignore                 # Git ignore rules

Agregar un nuevo servidor MCP

Crea el archivo del servidor

#!/usr/bin/env python3
"""
My Service MCP Server
Description of what it does
"""
import asyncio
from mcp.server import Server
# ... implement tools ...

Agrega configuración a .env.example

# My Service Configuration
MY_SERVICE_HOST=192.168.1.100
MY_SERVICE_API_KEY=your-api-key

Actualiza la documentación
- Agrega detalles del servidor a este README
- Actualiza PROJECT_INSTRUCTIONS.example.md
- Actualiza CLAUDE.md si agregas nuevos patrones o capacidades
- Agrega notas de seguridad si corresponde
Prueba exhaustivamente
- Prueba con infraestructura real
- Verifica el manejo de errores
- Verifica fugas de datos sensibles
- Revisa las implicaciones de seguridad

Variables de entorno

Todos los servidores MCP admiten dos métodos de configuración:

1. Variables de entorno (archivo .env)

Pares clave=valor simples
Cargadas automáticamente por cada servidor MCP
Buenas para configuraciones simples o pruebas

2. Inventario de Ansible (recomendado para producción)

Definición centralizada de infraestructura
Soporta agrupaciones complejas de hosts
Mejor para entornos con múltiples hosts
Establece ANSIBLE_INVENTORY_PATH en .env

Estándares de codificación

Sintaxis y características de Python 3.10+
Async/await para todas las operaciones de E/S
Anotaciones de tipo donde sea beneficioso
Manejo de errores para operaciones de red
Registro en stderr para depuración
Seguridad: Valida entradas, sanitiza salidas

Lista de verificación de pruebas

Antes de confirmar cambios:

Hook de seguridad de git instalado (python helpers/install_git_hook.py)
La verificación de seguridad manual pasa (python helpers/pre_publish_check.py)
Sin datos sensibles en código o confirmaciones
Variables de entorno para toda la configuración
Manejo de errores para fallos de red
El registro no expone secretos
Documentación actualizada
Implicaciones de seguridad revisadas
.gitignore actualizado si es necesario

🐛 Solución de problemas

Servidores MCP que no aparecen en Claude

Verifica la configuración de Claude Desktop:

# Windows
type %APPDATA%\Claude\claude_desktop_config.json

# Mac/Linux
cat ~/.config/Claude/claude_desktop_config.json

Verifica que la ruta de Python sea correcta en la configuración
Reinicia Claude Desktop completamente
Verifica los registros - Los servidores MCP registran en stderr

Errores de conexión

API de Docker/Podman:

# Test connectivity
curl http://your-host:2375/containers/json

# Check firewall
netstat -an | grep 2375

API de Pi-hole:

# Test API key
curl "http://your-pihole/api/stats/summary?sid=YOUR_API_KEY"

Ollama:

# Test Ollama endpoint
curl http://your-host:11434/api/tags

Comprensión de mensajes de error

Formato de mensaje de error (v2.2.0+):

Todos los servidores MCP ahora proporcionan mensajes de error detallados y procesables en este formato:

✗ [Service] [Error Type] (HTTP Status)

[Specific problem description]

Host: [hostname:port]

→ [Actionable remediation steps]

Technical details: [error details] (timestamp)

Tipos de error comunes:

1. Autenticación fallida (401)

Ejemplo:

✗ Pi-hole Authentication Failed (401)

Invalid API key for pi-hole-1

Host: 192.168.1.5:80

→ Verify PIHOLE_API_KEY_PI_HOLE_1 in .env matches your Pi-hole admin password.
→ You can find/reset this in Pi-hole Settings > API.

Cómo solucionarlo:

Verifica tu archivo .env para la variable de clave API correcta
Verifica que la clave API coincida con el panel de administración del servicio
Para Pi-hole: Configuración > API > Mostrar token de API
Para Unifi: Configuración > Administradores > API > Generar clave

2. Conexión fallida

Ejemplo:

✗ Unifi Connection Failed

Unable to connect to unifi-controller:443

Host: unifi-controller:443

→ Ensure Unifi controller is running and accessible at unifi-controller:443.
→ Test connectivity: nc -zv unifi-controller 443
→ Check firewall: sudo iptables -L | grep 443

Cómo solucionarlo:

Verifica que el servicio esté en ejecución: systemctl status [service-name]
Prueba la conectividad de red con nc o telnet
Verifica que las reglas de firewall permitan el acceso al puerto
Verifica que el nombre de host/IP sea correcto en tu configuración

3. Errores de tiempo de espera

Ejemplo:

✗ Ollama Timeout

Connection to ollama-1:11434 timed out (after 5s)

Host: ollama-1:11434

→ The service is not responding. Check if Ollama is running and not overloaded.
→ Check service status and logs for performance issues.

Cómo solucionarlo:

Verifica si el servicio está en ejecución: systemctl status ollama
Busca problemas de rendimiento en los registros del servicio
Verifica la latencia de red: ping [hostname]
Considera aumentar los valores de tiempo de espera si el servicio es legítimamente lento

4. Credenciales inválidas/expiradas (403)

Ejemplo:

✗ Service Authorization Failed (403)

Valid credentials but insufficient permissions

→ Ensure the API key/account has the required permissions for this operation.

Cómo solucionarlo:

Verifica los permisos de la cuenta en el panel de administración del servicio
Asegúrate de que la clave API tenga derechos de administrador/acceso completo
Regenera la clave API si los permisos se cambiaron recientemente

5. Errores del exportador de Unifi

Antes (v2.1.0):

Error: Exporter failed with code 1

Después (v2.2.0):

✗ Unifi Authentication Failed

Invalid Unifi API key for unifi-controller

Host: unifi-controller

→ Verify UNIFI_API_KEY in .env matches the API key from Unifi Settings > Admins > API.
→ Ensure the key has not expired.

Technical details: 401 Unauthorized (at 2025-11-20T10:30:45Z)

Cómo solucionarlo:

Inicia sesión en el controlador de Unifi
Navega a Configuración > Administradores > API
Verifica o regenera la clave API
Actualiza UNIFI_API_KEY en el archivo .env
Reinicia Claude Desktop para recargar la configuración

6. Servicio no disponible (503)

Cómo solucionarlo:

Verifica si el servicio está en ejecución
Busca errores de inicio del servicio en los registros
Verifica que todas las dependencias estén disponibles
Considera reiniciar el servicio

Consejos de depuración

Habilitar registro detallado:

Todos los errores se registran en stderr con contexto completo. Revisa los registros de Claude Desktop:

Windows: %APPDATA%\Claude\logs\
Mac: ~/Library/Logs/Claude/
Linux: ~/.config/Claude/logs/

Probar los endpoints de API directamente:

Usa curl o httpie para probar los endpoints de API fuera de MCP:

# Pi-hole
curl "http://pi-hole:80/api/stats/summary?sid=YOUR_API_KEY"

# Docker
curl http://docker-host:2375/containers/json

# Unifi (requires SSL and API key)
curl -k -H "X-API-KEY: YOUR_KEY" https://unifi:443/api/stat/sta

# Ollama
curl http://ollama:11434/api/tags

# NUT (Network UPS Tools)
telnet nut-server 3493
> LIST UPS

Verificar configuración:

# Verify .env file exists and is readable
ls -la .env

# Check for syntax errors in .env
cat .env | grep -v '^#' | grep -v '^$'

# Verify Ansible inventory
ansible-inventory -i ansible_hosts.yml --list

Errores de importación

Si obtienes errores de importación de Python:

# Reinstall dependencies
pip install --upgrade -r requirements.txt

# Verify MCP installation
pip show mcp

Errores de permisos

En Linux/Mac:

# Fix .env permissions
chmod 600 .env

# Make scripts executable
chmod +x *.py

📚 Recursos adicionales

Protocolo MCP

Proyectos relacionados

📄 Licencia

Licencia MIT - Consulta el archivo LICENSE para más detalles

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Consulta CONTRIBUTING.md para obtener pautas detalladas.

Para asistentes de IA y desarrolladores

📖 Lee CLAUDE.md primero - Este archivo contiene:

Arquitectura completa del proyecto y patrones de desarrollo
Requisitos de seguridad y errores comunes a evitar
Flujos de trabajo específicos para agregar funciones y corregir errores
Orientación específica para asistentes de IA al trabajar con este código base

Inicio rápido para contribuyentes

Instala el hook de seguridad de git (python helpers/install_git_hook.py)
Revisa las pautas de seguridad en SECURITY.md
Sin datos sensibles en los commits (el hook los bloqueará automáticamente)
Toda la configuración usa variables de entorno o Ansible
Actualiza la documentación para cualquier cambio
Prueba a fondo con infraestructura real

Proceso de solicitud de extracción (Pull Request)

Haz un fork del repositorio
Crea una rama de características (git checkout -b feature/amazing-feature)
Realiza tus cambios
Prueba con tu configuración de homelab
Actualiza el README y otros documentos según sea necesario
Haz commits con mensajes claros (git commit -m 'Add amazing feature')
Sube a tu fork (git push origin feature/amazing-feature)
Abre una solicitud de extracción

Criterios de revisión de código

Se siguen las mejores prácticas de seguridad
Sin credenciales ni IPs codificadas
Manejo adecuado de errores
El código sigue los patrones existentes
La documentación es clara y completa
Los cambios están probados

🙏 Agradecimientos

Anthropic por Claude y MCP
La comunidad de homelab por la inspiración
Contribuyentes y evaluadores

📞 Soporte

Problemas: GitHub Issues
Discusiones: GitHub Discussions
Seguridad: Consulta SECURITY.md para reportar vulnerabilidades

Recuerda: Este proyecto maneja infraestructura crítica. ¡Prioriza siempre la seguridad y prueba los cambios en un entorno seguro primero!