An MCP (Model Context Protocol) server that gives AI assistants like full control over your DNS ad-blocker - query logs, allow/deny lists, group management, gravity reload, and stats. Designed from day one for : manage one or many Pi-hole instances from a single MCP endpoint.
MCP server for Pi-hole v6 API — supports multiple instances
Pi-hole's admin API is powerful but cumbersome to script against. This MCP server turns every Pi-hole API action into a tool that any MCP-compatible AI assistant can call directly. Instead of clicking through the admin UI or writing curl commands, just ask your AI to check what's being blocked, allowlist a domain, or compare stats across instances.
Perfect for homelabbers running multiple Pi-holes (primary + secondary, or per-VLAN), network admins managing DNS filtering at scale, and anyone who wants AI-assisted DNS management.
Features
Multi-instance support - configure 1 to N Pi-hole instances via environment variables
Full Pi-hole v6 API coverage - query logs, allow/deny lists (full CRUD), group and client management, blocking control, local DNS (A + CNAME) records, gravity reload, stats
Smart regex detection - automatically routes domains to exact or regex lists based on metacharacter analysis
Regex landmine detector - finds deny-exact entries that look like they should be regex (miscategorized rules)
Docker-ready - multi-stage Dockerfile with non-root user, health checks, and security hardening
Streamable HTTP or stdio transport - run as a long-lived HTTP service, or let the MCP client spawn it on demand
Docker secrets support - passwords via env vars or /run/secrets/ files
Quick Start
Docker (recommended)
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
The MCP client starts the server as a child process when needed and talks to it over stdin/stdout. No port is opened and nothing keeps running in the background.
npm ci
npm run build
cp .env.example .env
chmod 600 .env
# Edit .env with your Pi-hole URL(s) and password(s)
Register it with Claude Code (user scope):
claude mcp add --scope user pihole -- bash -c \
'set -a; . ~/path/to/pihole-mcp/.env; set +a; MCP_TRANSPORT=stdio exec node ~/path/to/pihole-mcp/dist/index.js'
For each instance name in PIHOLE_INSTANCES, provide:
Variable
Required
Description
<NAME>_BASE_URL
Yes
Pi-hole base URL (e.g. http://pihole.local)
<NAME>_PASSWORD
Yes
Pi-hole API password (or use Docker secrets)
<NAME>_INSECURE_TLS
No
Set true for self-signed certs (default: false)
Docker secrets are supported as a fallback: /run/secrets/<name>_password (lowercase).
Available MCP Tools
Tool
Description
pihole_query_log
Fetch query log with filters (limit, time range, client IP or name, domain, status)
pihole_allow_domain
Add to allowlist (auto-detects exact vs regex)
pihole_deny_domain
Add to denylist (auto-detects exact vs regex)
pihole_list_allowlist
List all allowlist entries (exact + regex merged)
pihole_list_denylist
List all denylist entries (exact + regex merged)
pihole_stats_summary
Get Pi-hole statistics summary
pihole_reload_lists
Trigger gravity reload
pihole_group_management
CRUD operations on Pi-hole groups
pihole_client_management
CRUD operations on Pi-hole clients and their group assignments
pihole_check_regex_types
Detect miscategorized regex in deny-exact list
pihole_set_blocking
Enable/disable blocking, with optional auto-revert timer
pihole_domain_management
Update or delete an allow/deny domain (completes CRUD)
pihole_local_dns
List/add/delete local DNS A records
pihole_local_cname
List/add/delete local CNAME records
Every tool accepts an optional instance parameter to target a specific Pi-hole. Defaults to the first configured instance.
Connecting to Your MCP Client
This section applies to the HTTP transport (Docker or npm start). For stdio, see Local on demand.
The server listens on http://HOST:PORT/mcp (default: http://localhost:3000/mcp). The HTTP endpoint has no authentication, so keep it bound to localhost or a trusted network.