pihole-mcp

Un servidor MCP (Model Context Protocol) que brinda a asistentes de IA como Claude control total sobre tu bloqueador de anuncios DNS Pi-hole v6: registros de consultas, listas de permitidos/bloqueados, gestión de grupos, recarga de Gravity y estadísticas. Diseñado desde el primer día para despliegues multiinstancia: gestiona una o varias instancias de Pi-hole desde un único endpoint MCP.

¿Por qué?

La API de administración de Pi-hole es potente, pero incómoda a la hora de automatizar con scripts. Este servidor MCP convierte cada acción de la API de Pi-hole en una herramienta que cualquier asistente de IA compatible con MCP puede invocar directamente. En lugar de hacer clic en la interfaz de administración o escribir comandos curl, solo pídele a tu IA que compruebe qué se está bloqueando, que añada un dominio a la lista de permitidos o que compare estadísticas entre instancias.

Perfecto para aficionados al homelab que ejecutan varios Pi-holes (primario + secundario, o por VLAN), administradores de red que gestionan el filtrado DNS a gran escala y cualquier persona que quiera una gestión DNS asistida por IA.

Related MCP server: MCP Pi-hole Server

Características

• Soporte multiinstancia - configura de 1 a N instancias de Pi-hole mediante variables de entorno

• Cobertura completa de la API de Pi-hole v6 - registros de consultas, listas de permitidos/bloqueados (CRUD completo), gestión de grupos, control de bloqueo, registros DNS locales (A + CNAME), recarga de Gravity y estadísticas

• Detección inteligente de regex - enruta automáticamente los dominios a listas exactas o regex basándose en el análisis de metacaracteres

• Detector de minas regex - encuentra entradas deny-exact que parecen corresponder a regex (reglas mal clasificadas)

• Listo para Docker - Dockerfile multi-etapa con usuario no root, comprobaciones de salud y endurecimiento de seguridad

• Transporte HTTP por streaming - funciona con cualquier cliente MCP que admita MCP basado en HTTP

• Soporte de secretos de Docker - contraseñas mediante variables de entorno o archivos en /run/secrets/

Inicio rápido

Docker (recomendado)

git clone https://github.com/ranklancer/pihole-mcp.git
cd pihole-mcp
cp .env.example .env
# Edit .env with your Pi-hole URL(s) and password(s)

mkdir -p secrets
echo "your-pihole-password" > secrets/pihole_password
chmod 600 secrets/pihole_password

cp docker-compose.example.yml docker-compose.yml
docker compose up -d

Node.js

npm install
npm run build
export PIHOLE_INSTANCES=pihole
export PIHOLE_BASE_URL=http://pihole.example.com
export PIHOLE_PASSWORD=your-password
npm start

Configuración

Toda la configuración se realiza mediante variables de entorno. Consulta .env.example para la referencia completa.

Instancia única

PIHOLE_INSTANCES=pihole
PIHOLE_BASE_URL=http://192.0.2.100
PIHOLE_PASSWORD=your-password

Múltiples instancias

PIHOLE_INSTANCES=primary,secondary
PRIMARY_BASE_URL=http://192.0.2.100
PRIMARY_PASSWORD=password1
SECONDARY_BASE_URL=https://198.51.100.101
SECONDARY_PASSWORD=password2
SECONDARY_INSECURE_TLS=true

Para cada nombre de instancia en PIHOLE_INSTANCES, proporciona:

Los secretos de Docker se admiten como respaldo: /run/secrets/<name>_password (en minúsculas).

Herramientas MCP disponibles

Cada herramienta acepta un parámetro opcional instance para apuntar a una instancia específica de Pi-hole. Por defecto, se usa la primera instancia configurada.

Conectarse a tu cliente MCP

El servidor escucha en http://HOST:PORT/mcp (por defecto: http://localhost:3000/mcp).

Claude Desktop / Claude Code

Añade a tu configuración de MCP:

{
  "mcpServers": {
    "pihole": {
      "url": "http://localhost:3031/mcp"
    }
  }
}

Supergateway (envoltorio stdio)

Si tu cliente MCP solo admite transporte stdio, usa supergateway:

npx -y supergateway --streamableHttp http://localhost:3031/mcp

Comprobación de estado

curl http://localhost:3031/health
# {"ok":true,"service":"pihole-mcp","version":"0.3.0"}

Desarrollo

npm install
npm run dev     # Watch mode — recompiles on save
npm start       # Run the server

Requisitos

• Node.js >= 20

• Pi-hole v6 con acceso a la API habilitado

• Conectividad de red con tus instancias de Pi-hole

Proyectos relacionados

• Pi-hole — Bloqueo de anuncios en toda la red

• Model Context Protocol — Estándar abierto para la integración de herramientas de IA

• MCP Server Registry — Directorio de servidores MCP

Licencia

MIT