pihole-mcp
An MCP (Model Context Protocol) server that gives AI assistants like Claude full control over your Pi-hole v6 DNS ad-blocker - query logs, allow/deny lists, group management, gravity reload, and stats. Designed from day one for multi-instance deployments: manage one or many Pi-hole instances from a single MCP endpoint.
Why?
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, group management, 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 transport - works with any MCP client that supports HTTP-based MCP
- 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
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
Configuration
All configuration is via environment variables. See .env.example for the full reference.
Single Instance
PIHOLE_INSTANCES=pihole
PIHOLE_BASE_URL=http://192.168.1.100
PIHOLE_PASSWORD=your-password
Multiple Instances
PIHOLE_INSTANCES=primary,secondary
PRIMARY_BASE_URL=http://192.168.1.100
PRIMARY_PASSWORD=password1
SECONDARY_BASE_URL=https://192.168.1.101
SECONDARY_PASSWORD=password2
SECONDARY_INSECURE_TLS=true
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, 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 | |
... View full README on GitHub
