Pi-hole

pihole-mcp

Un servidor MCP de nivel de producción para Pi-hole v6.

76+ herramientas | 9 prompts | 5 recursos | Multi-instancia + sincronización | Binario Go único | Descarga de 6,4 MB (slim: 3,8 MB)

Da a los asistentes de IA control total sobre tu instancia de Pi-hole: bloqueo de DNS, gestión de dominios, análisis de consultas, estadísticas, dispositivos de red, DHCP y administración del sistema. Compatible con la API REST de Pi-hole v6.

Inicio rápido

La mayoría de los clientes MCP usan el mismo formato de configuración. Añade esto a la configuración de tu cliente:

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

Luego instala el binario mediante uno de los métodos siguientes.

Instalación

Registro MCP

pihole-mcp está listado en el Registro MCP oficial como:

io.github.hexamatic/pihole-mcp

Los clientes que admiten la instalación desde el registro pueden añadirlo con ese nombre y se les pedirá PIHOLE_URL y PIHOLE_PASSWORD. El listado apunta a la imagen ghcr.io, por lo que el cliente necesita Docker funcionando.

Homebrew

brew install hexamatic/tap/pihole-mcp

Se instala tanto en macOS como en Linux (Homebrew en Linux). En macOS, la cask elimina el atributo de cuarentena durante la instalación, por lo que el binario se ejecuta sin el aviso de Gatekeeper.

Scoop (Windows)

scoop bucket add hexamatic https://github.com/hexamatic/scoop-bucket
scoop install pihole-mcp

Instalación con Go

go install github.com/hexamatic/pihole-mcp/cmd/pihole-mcp@latest

Docker

docker pull ghcr.io/hexamatic/pihole-mcp:latest

Paquetes Linux

Los paquetes .deb y .rpm para distribuciones basadas en Debian (Ubuntu, Raspberry Pi OS) y basadas en RPM (Fedora, RHEL) están disponibles en la página de Releases.

# Debian / Ubuntu / Raspberry Pi OS
sudo dpkg -i pihole-mcp_X.Y.Z_linux_amd64.deb

# Fedora / RHEL / CentOS
sudo rpm -i pihole-mcp_X.Y.Z_linux_amd64.rpm

Descarga del binario

Los binarios precompilados para Linux, macOS y Windows (amd64 y arm64) están disponibles en la página de Releases.

Los releases incluyen checksums, están firmados con cosign sin clave y traen SBOM SPDX y procedencia de compilación SLSA; consulta SECURITY.md para los comandos de verificación.

Configuración

Se recomiendan contraseñas de aplicación para la automatización: omiten la 2FA TOTP y pueden revocarse de forma independiente.

PIHOLE_RATE_LIMIT y PIHOLE_ALLOWED_ORIGINS solo se aplican a los transportes http y sse; stdio es un canal de un solo proceso y un solo usuario por definición y no está limitado.

Múltiples instancias

Para gestionar más de un Pi-hole, configura instancias numeradas en lugar de PIHOLE_URL/PIHOLE_PASSWORD:

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_1_URL": "http://192.168.1.2",
        "PIHOLE_1_PASSWORD": "primary-password",
        "PIHOLE_1_NAME": "downstairs",
        "PIHOLE_2_URL": "http://192.168.1.3",
        "PIHOLE_2_PASSWORD": "secondary-password",
        "PIHOLE_2_NAME": "upstairs"
      }
    }
  }
}

Cada herramienta acepta entonces un argumento opcional instance, y cada resultado está etiquetado con la instancia de la que proviene. Omite el argumento para apuntar a la primera instancia; pasa un nombre para apuntar a una específica; pasa instance=all en una herramienta de solo lectura (p. ej. pihole_padd, pihole_stats_summary) para consultar todas las instancias de forma concurrente y obtener un único agregado estructurado (resultados por instancia más un resumen de éxito/fallo: una instancia lenta o inalcanzable ya no hace fallar toda la llamada). Las herramientas que cambian el estado requieren una única instancia nombrada. PIHOLE_URL y PIHOLE_1_URL son mutuamente excluyentes.

Mantener las instancias sincronizadas

Cuando ejecutas más de un Pi-hole, aparecen dos herramientas adicionales para mantenerlas alineadas:

• pihole_instance_diff — compara dos instancias y ve exactamente qué difiere entre adlists/allowlists, reglas de permitir/denegar (exactas y regex), grupos, clientes, registros DNS locales A/AAAA y registros CNAME. Es de solo lectura y no escribe nada.
• pihole_instance_sync — empuja la configuración de una instancia de origen a un destino. Es deliberadamente cauteloso:
  • Solo una dirección. Nombra la source de la verdad y el target; solo se escribe en el destino.
  • Primero una prueba en seco. Devuelve un plan y un confirm_token por defecto; nada cambia hasta que vuelves a ejecutarlo con mode=apply y ese token. Si la configuración se desvía entre la planificación y la aplicación, el token ya no coincide y la aplicación se rechaza.
  • Añadir/actualizar por defecto. Las entradas en el destino pero no en el origen se dejan intactas a menos que pases prune=true.
  • Con copia de seguridad. Se realiza una copia de seguridad teleporter del destino antes de cualquier cambio (desactívala con snapshot=false).
  • Seguro por omisión. Los ajustes específicos del host y de identidad (DHCP, enlaces de interfaz, contraseñas, certificados TLS, sesiones, 2FA) nunca se sincronizan. Las asociaciones de pertenencia a grupos tampoco se sincronizan, porque los IDs de grupo de Pi-hole son locales a cada instancia.

Ejemplo: previsualiza lo que le falta al Pi-hole upstairs en relación con downstairs y luego aplícalo.

pihole_instance_diff   { "source": "downstairs", "target": "upstairs" }
pihole_instance_sync   { "source": "downstairs", "target": "upstairs" }            → returns a plan + confirm_token
pihole_instance_sync   { "source": "downstairs", "target": "upstairs",
                         "mode": "apply", "confirm_token": "<token from the plan>" }

Configuración del cliente

La configuración de Inicio rápido anterior funciona para la mayoría de los clientes. Despliega la sección siguiente para instrucciones específicas por cliente.

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

claude mcp add pihole \
  -e PIHOLE_URL=http://192.168.1.2 \
  -e PIHOLE_PASSWORD=your-password \
  -- pihole-mcp

claude mcp list

{
  "servers": {
    "pihole": {
      "type": "stdio",
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PIHOLE_URL=http://192.168.1.2",
        "-e", "PIHOLE_PASSWORD=your-password",
        "-e", "TZ=Australia/Adelaide",
        "ghcr.io/hexamatic/pihole-mcp:latest"]
    }
  }
}

Herramientas

Un solo Pi-hole expone 76 herramientas. Configurar más de uno añade pihole_instance_diff y pihole_instance_sync, para un total de 78; solo se registran cuando hay una segunda instancia con la que comparar, por lo que una configuración de un solo Pi-hole no muestra herramientas que no puede usar.

Las tablas siguientes son un resumen; la referencia completa generada con cada parámetro está en docs/TOOLS.md.

Panel

Control de DNS

Estadísticas

Gestión de dominios

Grupos, clientes, listas

Registro de consultas

Sistema

Acciones y red

Multi-instancia (solo con más de un Pi-hole configurado)

Opciones de respuesta

La mayoría de las herramientas aceptan parámetros opcionales para controlar la salida:

• detail (minimal | normal | full) — Controla la profundidad de la respuesta. Predeterminado: normal. Usa minimal para resúmenes de una línea, full para datos completos de la API.
• format (text | csv) — Formato de salida para datos tabulares. Predeterminado: text. CSV ahorra ~29% de tokens. Disponible en pihole_domains_list, pihole_lists_list, pihole_clients_list, pihole_queries_search, pihole_network_devices, pihole_stats_top_domains, pihole_stats_top_clients, pihole_stats_upstreams, pihole_stats_query_types, pihole_stats_recent_blocked, pihole_stats_database_top_domains, pihole_stats_database_top_clients, pihole_stats_database_upstreams, pihole_dhcp_leases, y pihole_config_properties.

Prompts

Flujos de trabajo predefinidos de varios pasos para tareas comunes:

Recursos

Contexto de solo lectura que un cliente MCP puede obtener sin llamar a una herramienta:

Con más de un Pi-hole configurado, cada instancia también es direccionable directamente — pihole://instances las lista, y pihole://<instance>/status y pihole://<instance>/summary leen una instancia nombrada. Los URI sin prefijo anteriores siempre leen la primera instancia declarada.

Configuración Avanzada

Transporte

Por defecto, pihole-mcp usa stdio (estándar para MCP). También están disponibles los transportes HTTP y SSE:

# Default stdio (for Claude Desktop, Cursor, etc.)
pihole-mcp

# HTTP transport (for web-based MCP clients)
pihole-mcp -transport http -address localhost:8080

# SSE transport (deprecated — see below)
pihole-mcp -transport sse -address localhost:8080

SSE está obsoleto. La especificación MCP reemplazó el transporte HTTP+SSE con HTTP Streamable en la revisión del 2025-03-26. -transport sse se mantiene para clientes más antiguos y aún recibe correcciones de seguridad, pero los nuevos despliegues deberían usar -transport http. Se eliminará una vez que los clientes que lo necesitan hayan migrado.

Seguridad (transportes HTTP y SSE)

Los transportes http y sse aplican dos middlewares de seguridad a cada solicitud, de acuerdo con la guía de protección contra el rebinding de DNS de la especificación MCP 2025-11-25. stdio no se ve afectado (proceso único, usuario único).

• Validación de origen y host. Ambos encabezados deben resolverse a un host en PIHOLE_ALLOWED_ORIGINS (solo loopback por defecto). La falta de Origin se permite para clientes MCP que no son navegador. Las discrepancias devuelven HTTP 403. Para exponer pihole-mcp en una LAN, amplía la lista de permitidos:

  export PIHOLE_ALLOWED_ORIGINS="localhost,127.0.0.1,[::1],pihole-mcp.lan"
  

  El literal * desactiva la aplicación por completo — úsalo solo si estás detrás de un proxy inverso que hace su propio control de acceso.

• Límite de velocidad por sesión. Un cubo de tokens con clave Mcp-Session-Id (respaldo a IP del cliente) limita las solicitudes a PIHOLE_RATE_LIMIT por minuto (predeterminado 120, ráfaga max(120/4, 30)). Las solicitudes limitadas devuelven HTTP 429 con Retry-After: 1. 0 lo desactiva.

  # Tighter limit for a small fleet
  export PIHOLE_RATE_LIMIT=60
  
  # Disable (only when running behind a proxy with its own rate limit)
  export PIHOLE_RATE_LIMIT=0
  

OpenTelemetry

El rastreo es opcional. Establece OTEL_EXPORTER_OTLP_ENDPOINT para habilitarlo:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
pihole-mcp

Todas las llamadas a herramientas se rastrean automáticamente con nombre de herramienta, duración y estado de error.

Si no necesitas rastreo, la compilación slim elimina por completo las dependencias de OpenTelemetry SDK, gRPC, protobuf y grpc-gateway — un poco más de 40% más pequeña:

just build-slim
# or
go build -tags slim -o bin/pihole-mcp-slim ./cmd/pihole-mcp

# Docker
docker pull ghcr.io/hexamatic/pihole-mcp:latest-slim

El binario slim es funcionalmente idéntico excepto que OTEL_EXPORTER_OTLP_ENDPOINT se ignora.

Solución de Problemas

"Pi-hole rechazó el inicio de sesión: su grupo de sesiones API está lleno"

Pi-hole permite un número limitado de sesiones API concurrentes — webserver.api.max_sessions, 16 por defecto — y cada cliente que inicia sesión ocupa un lugar: la interfaz web, PADD, Home Assistant, cualquier otra integración y pihole-mcp. Cuando todos están ocupados, Pi-hole responde 429 y rechaza más inicios de sesión, incluso desde su propia interfaz web.

pihole-mcp libera su lugar al apagarse, pero una sesión dejada por un proceso que fue eliminado en lugar de detenido mantendrá uno hasta que expire. Tres formas de salir, en orden de preferencia:

1. Libera un lugar. Pide la lista de sesiones (pihole_auth_sessions) y revoca una que esté inactiva (pihole_auth_revoke_session).
2. Aumenta el límite. En una máquina con pocas integraciones, 16 es bajo:

   pihole-FTL --config webserver.api.max_sessions 32
   

3. Espera. Los lugares se liberan solos después de webserver.session.timeout — 30 minutos por defecto.

Reintentar no ayudará, por lo que pihole-mcp no lo hace: informa el problema en lugar de detenerse silenciosamente.

La autenticación falla con una contraseña correcta

Pi-hole limita la velocidad de los inicios de sesión fallidos repetidos, y el limitador no distingue entre "contraseña incorrecta" y "la contraseña que acabas de corregir". Espera unos segundos e inténtalo de nuevo. Si persiste, confirma que estás usando la contraseña de administrador o una contraseña de aplicación — no el código TOTP de la interfaz web.

Docker: "conexión rechazada" al llegar a Pi-hole

localhost dentro de un contenedor es el contenedor, no el host. Apunta PIHOLE_URL a la dirección LAN del host (http://192.168.1.2), a host.docker.internal en Docker Desktop, o pon ambos contenedores en la misma red Docker y usa el nombre del contenedor de Pi-hole.

Las marcas de tiempo se muestran en UTC

Cada marca de tiempo en la salida de la herramienta lleva un marcador de zona explícito (p. ej. 19 Jul 2026, 9:41 AM UTC), por lo que las respuestas son inequívocas sea cual sea la zona. La zona utilizada depende de dónde se ejecuta el servidor: los binarios nativos usan la zona horaria del sistema, mientras que la imagen Docker usa UTC por defecto. Para obtener horas locales desde el contenedor, establece TZ en el contenedor pihole-mcp (no solo el de Pi-hole) — los datos de zona horaria están incrustados en el binario, por lo que no se necesitan paquetes adicionales ni montajes de volumen:

environment:
  - TZ=Australia/Adelaide

Un valor no reconocido de TZ registra una advertencia al inicio y vuelve a UTC en lugar de negarse a iniciar.

"x509: certificado firmado por autoridad desconocida"

Tu Pi-hole está sirviendo HTTPS con un certificado autofirmado, que falla la verificación TLS estándar. La solución correcta es un certificado de confianza en el Pi-hole (por ejemplo, a través de su configuración de dominio integrada o un proxy inverso con Let's Encrypt). Si eso no es práctico, establece PIHOLE_TLS_SKIP_VERIFY=true para desactivar la verificación — las conexiones siguen cifradas, pero la identidad del servidor ya no se comprueba, así que úsalo solo en una red que controles.

Caídas de conexión ocasionales

El servidor web integrado de Pi-hole cierra conexiones bajo carga. pihole-mcp reintenta estas automáticamente con retroceso; si ves fallos de todos modos, aumenta PIHOLE_MAX_RETRIES (predeterminado 3).

Desarrollo

# Prerequisites: Go 1.26+, Docker, mise, just

# One-command setup
just setup

# Start local Pi-hole (http://localhost:8081, password: test)
just dev-up

# Run quality checks (format + lint + test)
just check

# Run integration tests against local Pi-hole
just integration

# Build binary
just build

Consulta CONTRIBUTING.md para las pautas completas de desarrollo.

Pi-hole es una marca registrada de Pi-hole LLC. Este proyecto se mantiene de forma independiente y no está afiliado, respaldado ni patrocinado por Pi-hole LLC.

Licencia

MIT