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`	Get Pi-hole statistics summary
`pihole_reload_lists`	Trigger gravity reload
`pihole_group_management`	CRUD operations on Pi-hole groups
`pihole_check_regex_types`	Detect miscategorized regex in deny-exact list

Every tool accepts an optional instance parameter to target a specific Pi-hole. Defaults to the first configured instance.

Connecting to Your MCP Client

The server listens on http://HOST:PORT/mcp (default: http://localhost:3000/mcp).

Claude Desktop / Claude Code

Add to your MCP settings:

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

Supergateway (stdio wrapper)

If your MCP client only supports stdio transport, use supergateway:

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

Health Check

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

Development

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

Requirements

Node.js >= 20
Pi-hole v6 with API access enabled
Network connectivity to your Pi-hole instance(s)

Related Projects

Pi-hole — Network-wide ad blocking
Model Context Protocol — Open standard for AI tool integration
MCP Server Registry — Directory of MCP servers

License

MIT

Pi-hole MCP Server

Quick Install