pihole-mcp

Einheitlicher Pi-hole v6 MCP-Server. Fasst die nützlichen Tools aus drei Upstream-MCPs (aplaceforallmystuff/mcp-pihole, sbarbett/pihole-mcp-server, cwdcwd/mcp-server-pihole) in einem Python-Server zusammen, der dem chris2ao-unifi-mcp-Stack (FastMCP + httpx + Pydantic v2) entspricht.

Tools (28)

Statistiken (8): get_stats, get_top_blocked, get_top_permitted, get_top_clients, get_query_types, get_forward_destinations, get_recent_blocked, get_history

Abfragen (2): get_query_log (umfangreiche Filter: Zeitbereich, Domain, Client, Upstream, Cursor), get_query_suggestions

Blockierung (3): get_blocking_status, enable_blocking, disable_blocking (mit optionalem Timer)

Domain-Listen (6): get_whitelist, get_blacklist, add_to_whitelist, add_to_blacklist, remove_from_whitelist, remove_from_blacklist

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

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

Plus server_info.

Siehe docs/plans/consolidated-tool-map.md für die Tool-zu-Endpunkt-Zuordnung.

Related MCP server: Pi-hole MCP Server

Authentifizierung

Pi-hole v6 verwendet eine sitzungsbasierte Authentifizierung. Dieser Server handhabt dies automatisch:

1. POST /api/auth mit {"password": "<app-password>"} gibt eine Sitzungs-SID zurück.

2. Alle nachfolgenden Aufrufe enthalten X-FTL-SID: <sid>.

3. Bei einem 401-Fehler oder kurz vor Ablauf der Gültigkeit authentifiziert sich der Client erneut und versucht es einmal erneut.

4. Beim Herunterfahren gibt DELETE /api/auth die Sitzung frei.

Das App-Passwort wird in der Pi-hole Web-UI erstellt: Einstellungen > Web-Oberfläche > "Anwendungspasswort" > Generieren. Dies ist getrennt vom Haupt-Admin-Web-Passwort und ist das korrekte Anmeldeinformations-Format für API-Clients.

Installation

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

Oder über den Wrapper (Produktionseinsatz mit Claude Code):

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

Registrierung bei Claude Code

Fügen Sie in ~/.claude.json Folgendes zu mcpServers hinzu:

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

Der Wrapper lädt ~/.claude/secrets/secrets.env für PIHOLE_URL und PIHOLE_PASSWORD und ruft dann uv run auf.

Entwicklung

• Tests ausführen: uv run pytest

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

• Python: 3.12+

Beziehung zu chris2ao-unifi-mcp

Gleicher Stack (FastMCP, httpx, Pydantic-settings, hatchling, uv). Einfacher als unifi-mcp, da Pi-hole ein einzelnes Produkt ist (kein dynamisches Laden oder Erkennen von Produkten). Wenn Sie dies für mehrere Pi-holes oder für die fehlenden Punkte (Adlist/Gravity CRUD, Gruppen, DHCP, Teleporter) erweitern, folgen Sie dem Modul-pro-Fähigkeit-Muster von unifi-mcp.