pihole-mcp

Servidor MCP unificado para Pi-hole v6. Consolida las herramientas útiles de tres MCPs ascendentes (aplaceforallmystuff/mcp-pihole, sbarbett/pihole-mcp-server, cwdcwd/mcp-server-pihole) en un único servidor Python que coincide con la pila chris2ao-unifi-mcp (FastMCP + httpx + Pydantic v2).

Herramientas (28)

Estadísticas (8): get_stats, get_top_blocked, get_top_permitted, get_top_clients, get_query_types, get_forward_destinations, get_recent_blocked, get_history

Consultas (2): get_query_log (filtros avanzados: rango de tiempo, dominio, cliente, upstream, cursor), get_query_suggestions

Bloqueo (3): get_blocking_status, enable_blocking, disable_blocking (con temporizador opcional)

Listas de dominios (6): get_whitelist, get_blacklist, add_to_whitelist, add_to_blacklist, remove_from_whitelist, remove_from_blacklist

DNS local (5): list_local_dns, add_local_a_record, remove_local_a_record, add_local_cname_record, remove_local_cname_record

Mantenimiento (4): update_gravity, flush_cache, flush_logs, get_tail_log

Además de server_info.

Consulte docs/plans/consolidated-tool-map.md para ver el mapeo de endpoints por herramienta.

Related MCP server: Pi-hole MCP Server

Autenticación

Pi-hole v6 utiliza autenticación basada en sesiones. Este servidor la gestiona automáticamente:

1. POST /api/auth con {"password": "<app-password>"} devuelve un SID de sesión.

2. Todas las llamadas posteriores incluyen X-FTL-SID: <sid>.

3. En caso de error 401 o proximidad de caducidad, el cliente se vuelve a autenticar y reintenta una vez.

4. Al apagarse, DELETE /api/auth libera la sesión.

La contraseña de la aplicación se crea en la interfaz web de Pi-hole: Ajustes > Interfaz web > "Application password" > Generar. Esta es distinta de la contraseña principal de administración web y es la credencial correcta para los clientes de la API.

Instalación

cd /Users/chris2ao/GitProjects/chris2ao-pihole-mcp
uv sync
cp .env.example .env   # fill in PIHOLE_URL and PIHOLE_PASSWORD
uv run pytest

O mediante el envoltorio (uso en producción con Claude Code):

~/.claude/scripts/pihole-wrapper.sh

Registrar en Claude Code

En ~/.claude.json, añada a mcpServers:

"pihole": {
  "command": "/Users/chris2ao/.claude/scripts/pihole-wrapper.sh",
  "args": []
}

El envoltorio obtiene PIHOLE_URL y PIHOLE_PASSWORD de ~/.claude/secrets/secrets.env y luego invoca uv run.

Desarrollo

• Ejecutar pruebas: uv run pytest

• Cobertura: uv run pytest --cov --cov-report=term

• Python: 3.12+

Relación con chris2ao-unifi-mcp

Misma pila (FastMCP, httpx, Pydantic-settings, hatchling, uv). Más sencillo que unifi-mcp porque Pi-hole es un producto único (sin carga dinámica de productos ni descubrimiento). Si amplía esto para múltiples Pi-hole o para los elementos faltantes (CRUD de adlist/gravity, grupos, DHCP, Teleporter), siga el patrón de módulo por capacidad de unifi-mcp.