Pi-hole MCP Server — Claude Code MCP server for DNS control
Lets an AI assistant drive Pi-hole v6: DNS blocking, domains, clients, query stats, DHCP, and syncing between two instances.
claude mcp add --env PIHOLE_URL=<PIHOLE_URL> --env PIHOLE_PASSWORD=<PIHOLE_PASSWORD> --env TZ=<TZ> --env PIHOLE_READ_ONLY=<PIHOLE_READ_ONLY> --env PIHOLE_TLS_SKIP_VERIFY=<PIHOLE_TLS_SKIP_VERIFY> --transport stdio pi-hole-mcp-server -- docker run -i --rm -e PIHOLE_URL -e PIHOLE_PASSWORD -e TZ -e PIHOLE_READ_ONLY -e PIHOLE_TLS_SKIP_VERIFY ghcr.io/hexamatic/pihole-mcp:0.9.0What Pi-hole MCP Server does
The server ships as a single Go binary and talks to the Pi-hole v6 REST API. It carries 82 tools (84 with a second Pi-hole configured), 9 prompts and 5 resources: domains, lists, groups, clients, DHCP, network, the query log, local DNS records, teleporter backup and restore, session handling. You ask in plain language; the assistant picks the tool.
Locking it down is a first-class option. With PIHOLE_READ_ONLY=true only non-mutating tools are exposed, and that check runs on every call rather than relying on whatever list the client cached. PIHOLE_TOOLSETS trims the surface further to the families you actually need. Two Pi-holes can be compared, and changes reconciled one onto the other through a dry-run plan plus a confirm token before any write.
Run pihole-mcp -check before wiring the server into a client. It loads the config, contacts each configured Pi-hole and reports it by name, exiting non-zero on failure. Skip that step and a wrong URL or password looks identical to a server that never started, because most clients swallow the output. PIHOLE_URL and PIHOLE_PASSWORD are both required; the examples below run the ghcr.io/hexamatic/pihole-mcp:0.9.0 image through Docker.
What it helps with
- check whether DNS blocking is on and how long it lasts
- pause blocking while testing a site
- find which list a blocked domain came from
- add a local DNS record for a home server
- diff two Pi-holes and push the differences
Example prompts for the agent
- Pause blocking for ten minutes, I need to test something
- Which lists is this domain on?
How to install Pi-hole MCP Server
Platform CLI
claude mcp add --env PIHOLE_URL=<PIHOLE_URL> --env PIHOLE_PASSWORD=<PIHOLE_PASSWORD> --env TZ=<TZ> --env PIHOLE_READ_ONLY=<PIHOLE_READ_ONLY> --env PIHOLE_TLS_SKIP_VERIFY=<PIHOLE_TLS_SKIP_VERIFY> --transport stdio pi-hole-mcp-server -- docker run -i --rm -e PIHOLE_URL -e PIHOLE_PASSWORD -e TZ -e PIHOLE_READ_ONLY -e PIHOLE_TLS_SKIP_VERIFY ghcr.io/hexamatic/pihole-mcp:0.9.0Replace <…> with your own values. 3 more environment variables are in the server README
Platform CLI
codex mcp add pi-hole-mcp-server --env PIHOLE_URL=<PIHOLE_URL> --env PIHOLE_PASSWORD=<PIHOLE_PASSWORD> --env TZ=<TZ> --env PIHOLE_READ_ONLY=<PIHOLE_READ_ONLY> --env PIHOLE_TLS_SKIP_VERIFY=<PIHOLE_TLS_SKIP_VERIFY> -- docker run -i --rm -e PIHOLE_URL -e PIHOLE_PASSWORD -e TZ -e PIHOLE_READ_ONLY -e PIHOLE_TLS_SKIP_VERIFY ghcr.io/hexamatic/pihole-mcp:0.9.0Replace <…> with your own values. 3 more environment variables are in the server README
Config file
{
"mcpServers": {
"pi-hole-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"PIHOLE_URL",
"-e",
"PIHOLE_PASSWORD",
"-e",
"TZ",
"-e",
"PIHOLE_READ_ONLY",
"-e",
"PIHOLE_TLS_SKIP_VERIFY",
"ghcr.io/hexamatic/pihole-mcp:0.9.0"
],
"env": {
"PIHOLE_URL": "<PIHOLE_URL>",
"PIHOLE_PASSWORD": "<PIHOLE_PASSWORD>",
"TZ": "<TZ>",
"PIHOLE_READ_ONLY": "<PIHOLE_READ_ONLY>",
"PIHOLE_TLS_SKIP_VERIFY": "<PIHOLE_TLS_SKIP_VERIFY>"
}
}
}
}Replace <…> with your own values. 3 more environment variables are in the server README
Config file
{
"servers": {
"pi-hole-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"PIHOLE_URL",
"-e",
"PIHOLE_PASSWORD",
"-e",
"TZ",
"-e",
"PIHOLE_READ_ONLY",
"-e",
"PIHOLE_TLS_SKIP_VERIFY",
"ghcr.io/hexamatic/pihole-mcp:0.9.0"
],
"env": {
"PIHOLE_URL": "<PIHOLE_URL>",
"PIHOLE_PASSWORD": "<PIHOLE_PASSWORD>",
"TZ": "<TZ>",
"PIHOLE_READ_ONLY": "<PIHOLE_READ_ONLY>",
"PIHOLE_TLS_SKIP_VERIFY": "<PIHOLE_TLS_SKIP_VERIFY>"
}
}
}
}Replace <…> with your own values. 3 more environment variables are in the server README
Platform CLI
gemini mcp add -e PIHOLE_URL=<PIHOLE_URL> -e PIHOLE_PASSWORD=<PIHOLE_PASSWORD> -e TZ=<TZ> -e PIHOLE_READ_ONLY=<PIHOLE_READ_ONLY> -e PIHOLE_TLS_SKIP_VERIFY=<PIHOLE_TLS_SKIP_VERIFY> pi-hole-mcp-server docker run -i --rm -e PIHOLE_URL -e PIHOLE_PASSWORD -e TZ -e PIHOLE_READ_ONLY -e PIHOLE_TLS_SKIP_VERIFY ghcr.io/hexamatic/pihole-mcp:0.9.0Replace <…> with your own values. 3 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Pi-hole MCP Server
How do I install Pi-hole MCP Server in Claude Code?
Run `claude mcp add --env PIHOLE_URL=<PIHOLE_URL> --env PIHOLE_PASSWORD=<PIHOLE_PASSWORD> --env TZ=<TZ> --env PIHOLE_READ_ONLY=<PIHOLE_READ_ONLY> --env PIHOLE_TLS_SKIP_VERIFY=<PIHOLE_TLS_SKIP_VERIFY> --transport stdio pi-hole-mcp-server -- docker run -i --rm -e PIHOLE_URL -e PIHOLE_PASSWORD -e TZ -e PIHOLE_READ_ONLY -e PIHOLE_TLS_SKIP_VERIFY ghcr.io/hexamatic/pihole-mcp:0.9.0`. Fill in your Pi-hole address, password and timezone.
What does Pi-hole MCP Server do?
It gives an assistant control over Pi-hole v6: DNS blocking, domains and lists, clients, the query log, statistics, DHCP, local DNS records, teleporter backups. It also compares two Pi-holes and reconciles them.
Can I use it without risking any changes?
Yes. Set PIHOLE_READ_ONLY=true and only tools that cannot modify Pi-hole stay available, enforced on every call. PIHOLE_TOOLSETS narrows the set to the families you need.
