# Pi-hole MCP Server Lets an AI assistant drive Pi-hole v6: DNS blocking, domains, clients, query stats, DHCP, and syncing between two instances. - MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 8 - Author: hexamatic - License: MIT · policy=link-only · description only; the file stays with the author - Source: https://github.com/hexamatic/pihole-mcp - Updated: 2026-10-19 - HTML: https://affpapa.org/en/nevibecode/mcp/pi-hole-mcp-server ## What it 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. ## Requirements - Needs: Docker - Environment variables: `PIHOLE_URL`, `PIHOLE_PASSWORD`, `TZ`, `PIHOLE_READ_ONLY`, `PIHOLE_TLS_SKIP_VERIFY`, `PIHOLE_REQUEST_TIMEOUT`, `PIHOLE_MAX_RETRIES`, `PIHOLE_RETRY_MAX_DELAY` — keys and tokens: ask the human for the values, never commit them or put them in shared files. ## Install ### Claude Code (native platform) **Platform CLI** ```bash claude mcp add --env PIHOLE_URL= --env PIHOLE_PASSWORD= --env TZ= --env PIHOLE_READ_ONLY= --env 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 ``` Replace <…> with your own values. 3 more environment variables are in the server README ### Codex **Platform CLI** ```bash codex mcp add pi-hole-mcp-server --env PIHOLE_URL= --env PIHOLE_PASSWORD= --env TZ= --env PIHOLE_READ_ONLY= --env 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.0 ``` Replace <…> with your own values. 3 more environment variables are in the server README ### Cursor **Config file** File `.cursor/mcp.json`: ```json { "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_PASSWORD": "", "TZ": "", "PIHOLE_READ_ONLY": "", "PIHOLE_TLS_SKIP_VERIFY": "" } } } } ``` Replace <…> with your own values. 3 more environment variables are in the server README ### GitHub Copilot **Config file** File `.vscode/mcp.json`: ```json { "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_PASSWORD": "", "TZ": "", "PIHOLE_READ_ONLY": "", "PIHOLE_TLS_SKIP_VERIFY": "" } } } } ``` Replace <…> with your own values. 3 more environment variables are in the server README ### Gemini CLI **Platform CLI** ```bash gemini mcp add -e PIHOLE_URL= -e PIHOLE_PASSWORD= -e TZ= -e PIHOLE_READ_ONLY= -e 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.0 ``` Replace <…> with your own values. 3 more environment variables are in the server README ## When to use it - 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 - Pause blocking for ten minutes, I need to test something - Which lists is this domain on? ## Similar - [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918 - [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115 - [Oh My Posh Validator](https://affpapa.org/en/nevibecode/mcp/oh-my-posh-validator.md) — MCP server · ★ 23643 - [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18727 - [Coder](https://affpapa.org/en/nevibecode/mcp/coder.md) — MCP server · ★ 17160 - [mcp](https://affpapa.org/en/nevibecode/mcp/kubeshark-mcp.md) — MCP server · ★ 12109 --- NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md