mcp-pihole — Claude Code MCP server for Pi-hole DNS control
Wires Pi-hole v6 into your AI assistant: query stats, allow and deny lists, blocking on and off, all through plain sentences.
claude mcp add mcp-pihole -e PIHOLE_URL=<PIHOLE_URL> -e PIHOLE_PASSWORD=<PIHOLE_PASSWORD> -- npx -y mcp-pihole-serverWhat mcp-pihole does
The server talks to your Pi-hole over the v6 API. Ask which domains get blocked most often, or which clients fire the most queries, and you get numbers back. Tell it to pause blocking for a few minutes and it does. List edits happen without opening the web UI.
Tools cover statistics (pihole_get_stats, pihole_get_top_blocked, pihole_get_top_permitted, pihole_get_top_clients, pihole_get_query_log), blocking control, allow and deny list CRUD, gravity updates and DNS cache flushes. Four statistics tools accept visualize: true and answer with an ANSI-colored ASCII dashboard instead of JSON.
You need Node.js 18+, Pi-hole v6 with the API switched on, and an app password generated in Pi-hole settings. That password shows once at creation, so copy it then. The machine running your assistant has to reach Pi-hole over the network.
What it helps with
- see which domains get blocked most
- pause blocking for a set time and restore it
- add a domain to the allow list without the web UI
- find which clients send the most DNS queries
- refresh gravity and clear the DNS cache
Example prompts for the agent
- Show me Pi-hole stats
- Disable Pi-hole for 5 minutes
- Add example.com to the whitelist
How to install mcp-pihole
Platform CLI
claude mcp add mcp-pihole -e PIHOLE_URL=<PIHOLE_URL> -e PIHOLE_PASSWORD=<PIHOLE_PASSWORD> -- npx -y mcp-pihole-serverReplace <…> with your own values
Platform CLI
codex mcp add mcp-pihole --env PIHOLE_URL=<PIHOLE_URL> --env PIHOLE_PASSWORD=<PIHOLE_PASSWORD> -- npx -y mcp-pihole-serverReplace <…> with your own values
Config file
{
"mcpServers": {
"mcp-pihole": {
"command": "npx",
"args": [
"-y",
"mcp-pihole-server"
],
"env": {
"PIHOLE_URL": "<PIHOLE_URL>",
"PIHOLE_PASSWORD": "<PIHOLE_PASSWORD>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"mcp-pihole": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-pihole-server"
],
"env": {
"PIHOLE_URL": "<PIHOLE_URL>",
"PIHOLE_PASSWORD": "<PIHOLE_PASSWORD>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e PIHOLE_URL=<PIHOLE_URL> -e PIHOLE_PASSWORD=<PIHOLE_PASSWORD> mcp-pihole npx -y mcp-pihole-serverReplace <…> with your own values
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 mcp-pihole
How do I install mcp-pihole in Claude Code?
Run claude mcp add mcp-pihole -e PIHOLE_URL=<PIHOLE_URL> -e PIHOLE_PASSWORD=<PIHOLE_PASSWORD> -- npx -y mcp-pihole-server. Fill in your Pi-hole web address and app password.
What does mcp-pihole do?
It exposes Pi-hole to the assistant: query statistics, top domains and clients, the DNS query log, blocking control, allow and deny list edits, gravity updates and cache flushes.
What does mcp-pihole need to run?
Node.js 18+, Pi-hole v6 with the API enabled, and an app password from Pi-hole settings. Pass PIHOLE_URL and PIHOLE_PASSWORD when adding the server.
