pihole-mcp

Ein MCP (Model Context Protocol)-Server, der KI-Assistenten wie Claude die volle Kontrolle über Ihren Pi-hole v6 DNS-Werbeblocker gibt – Protokolle abfragen, Erlaubnis-/Sperrlisten, Gruppenverwaltung, Gravity-Neuladen und Statistiken. Von Anfang an für Multi-Instanz-Bereitstellungen konzipiert: Verwalten Sie eine oder viele Pi-hole-Instanzen über einen einzigen MCP-Endpunkt.

Warum?

Die Admin-API von Pi-hole ist leistungsfähig, aber umständlich zu skripten. Dieser MCP-Server verwandelt jede Pi-hole-API-Aktion in ein Werkzeug, das jeder MCP-kompatible KI-Assistent direkt aufrufen kann. Statt durch die Admin-Oberfläche zu klicken oder curl-Befehle zu schreiben, können Sie Ihre KI einfach bitten, zu prüfen, was blockiert wird, eine Domain auf die Whitelist zu setzen oder Statistiken über Instanzen hinweg zu vergleichen.

Perfekt für Homelab-Betreiber, die mehrere Pi-holes betreiben (primär + sekundär oder pro VLAN), Netzwerkadministratoren, die DNS-Filterung in großem Maßstab verwalten, und alle, die KI-gestützte DNS-Verwaltung wünschen.

Related MCP server: MCP Pi-hole Server

Funktionen

• Multi-Instanz-Unterstützung – Konfigurieren Sie 1 bis N Pi-hole-Instanzen über Umgebungsvariablen

• Vollständige Pi-hole-v6-API-Abdeckung – Protokolle abfragen, Erlaubnis-/Sperrlisten (vollständiges CRUD), Gruppenverwaltung, Blockierungssteuerung, lokale DNS-Einträge (A + CNAME), Gravity-Neuladen, Statistiken

• Intelligente Regex-Erkennung – Leitet Domains automatisch an exakte oder Regex-Listen weiter, basierend auf Metazeichen-Analyse

• Regex-Minenfeld-Erkennung – Findet Deny-Exact-Einträge, die wie Regex aussehen (falsch kategorisierte Regeln)

• Docker-bereit – Mehrstufiges Dockerfile mit Nicht-Root-Benutzer, Health Checks und Sicherheitshärtung

• Streamable-HTTP-Transport – Funktioniert mit jedem MCP-Client, der HTTP-basiertes MCP unterstützt

• Docker-Secrets-Unterstützung – Passwörter über Umgebungsvariablen oder /run/secrets/-Dateien

Schnellstart

Docker (empfohlen)

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

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen. Siehe .env.example für die vollständige Referenz.

Einzelne Instanz

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

Mehrere Instanzen

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

Für jeden Instanznamen in PIHOLE_INSTANCES angeben:

Docker-Secrets werden als Fallback unterstützt: /run/secrets/<name>_password (Kleinbuchstaben).

Verfügbare MCP-Tools

Jedes Tool akzeptiert einen optionalen Parameter instance, um eine bestimmte Pi-hole-Instanz anzusprechen. Standardmäßig wird die erste konfigurierte Instanz verwendet.

Verbindung zu Ihrem MCP-Client herstellen

Der Server lauscht auf http://HOST:PORT/mcp (Standard: http://localhost:3000/mcp).

Claude Desktop / Claude Code

Fügen Sie zu Ihren MCP-Einstellungen hinzu:

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

Supergateway (stdio-Wrapper)

Wenn Ihr MCP-Client nur stdio-Transport unterstützt, verwenden Sie supergateway:

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

Health Check

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

Entwicklung

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

Anforderungen

• Node.js >= 20

• Pi-hole v6 mit aktiviertem API-Zugriff

• Netzwerkverbindung zu Ihrer/ Ihren Pi-hole-Instanz(en)

Verwandte Projekte

• Pi-hole – Netzwerkweite Werbeblockierung

• Model Context Protocol – Offener Standard für KI-Tool-Integration

• MCP Server Registry – Verzeichnis von MCP-Servern

Lizenz

MIT