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.

Related MCP server: MCP Pi-hole Server

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

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

Local on demand (stdio, no Docker)

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'

Or add it manually to your MCP client config:

{
  "mcpServers": {
    "pihole": {
      "type": "stdio",
      "command": "bash",
      "args": ["-c", "set -a; . ~/path/to/pihole-mcp/.env; set +a; MCP_TRANSPORT=stdio exec node ~/path/to/pihole-mcp/dist/index.js"]
    }
  }
}

HOST and PORT from .env are ignored in stdio mode.

Configuration

All configuration is via environment variables. See .env.example for the full reference.

Single Instance

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

Multiple Instances

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

For each instance name in PIHOLE_INSTANCES, provide:

Docker secrets are supported as a fallback: /run/secrets/<name>_password (lowercase).

Available MCP Tools

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.

Claude Desktop / Claude Code

Add to your MCP settings:

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

Health Check

curl http://localhost:3031/health
# {"ok":true,"service":"pihole-mcp","version":"0.3.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