
Pi-hole MCP Server
Manage Pi-hole v6 DNS blocking, domains, clients, DHCP and query logs from an assistant
- Pricing
- Open source
- Platforms
- CLI, macOS, Windows
- Runs
- Locally
- Version
- 0.10.0
- Listing updated
- 2 days ago
About Pi-hole MCP Server
Pi-hole MCP Server is an open-source MCP server for cloud and infrastructure. It runs locally on your machine and is started by your AI client.
This Go server covers roughly 95% of the Pi-hole v6 REST API with 82 tools (84 when a second instance is configured), nine prompts and five resources. You can ask whether blocking is on, pause it for ten minutes, trace why a domain is blocked across every list it could be on, add a local DNS record, find unrecognised network devices or check which upstream resolver is slowest.
Safety controls are the focus. Setting PIHOLE_READ_ONLY hides and rejects every tool that can change anything, enforced on each call, and PIHOLE_TOOLSETS limits it to the families you need. With two Pi-holes, it can diff them and reconcile one onto the other using a dry-run plan and a confirm token before writing. A -check flag tests connections and warns about FTL releases with published security advisories.
Releases carry cosign signatures, SPDX SBOMs and SLSA provenance. Install through Homebrew, Scoop, go install, Docker, deb or rpm packages. Configuration is a Pi-hole URL plus an admin or application password, and an application password bypasses TOTP.
Install
Run in a terminal
claude mcp add pihole-mcp --env PIHOLE_URL='<PIHOLE_URL>' --env PIHOLE_PASSWORD='<PIHOLE_PASSWORD>' -- docker run -i --rm -e PIHOLE_URL -e PIHOLE_PASSWORD ghcr.io/hexamatic/pihole-mcp:0.10.0Add to claude_desktop_config.json
{
"mcpServers": {
"pihole-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"PIHOLE_URL",
"-e",
"PIHOLE_PASSWORD",
"ghcr.io/hexamatic/pihole-mcp:0.10.0"
],
"env": {
"PIHOLE_URL": "<PIHOLE_URL>",
"PIHOLE_PASSWORD": "<PIHOLE_PASSWORD>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"pihole-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"PIHOLE_URL",
"-e",
"PIHOLE_PASSWORD",
"ghcr.io/hexamatic/pihole-mcp:0.10.0"
],
"env": {
"PIHOLE_URL": "<PIHOLE_URL>",
"PIHOLE_PASSWORD": "<PIHOLE_PASSWORD>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"pihole-mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"PIHOLE_URL",
"-e",
"PIHOLE_PASSWORD",
"ghcr.io/hexamatic/pihole-mcp:0.10.0"
],
"env": {
"PIHOLE_URL": "<PIHOLE_URL>",
"PIHOLE_PASSWORD": "<PIHOLE_PASSWORD>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"pihole-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"PIHOLE_URL",
"-e",
"PIHOLE_PASSWORD",
"ghcr.io/hexamatic/pihole-mcp:0.10.0"
],
"env": {
"PIHOLE_URL": "<PIHOLE_URL>",
"PIHOLE_PASSWORD": "<PIHOLE_PASSWORD>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"pihole-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"PIHOLE_URL",
"-e",
"PIHOLE_PASSWORD",
"ghcr.io/hexamatic/pihole-mcp:0.10.0"
],
"env": {
"PIHOLE_URL": "<PIHOLE_URL>",
"PIHOLE_PASSWORD": "<PIHOLE_PASSWORD>"
}
}
}
}Configuration
PIHOLE_URLBase URL of your Pi-hole web interface. For multiple Pi-holes use PIHOLE_1_URL, PIHOLE_2_URL, ... instead.RequiredPIHOLE_PASSWORDPi-hole admin password, or an application password (recommended — bypasses TOTP 2FA)RequiredTZIANA timezone for rendered timestamps, e.g. Australia/Adelaide. Defaults to UTC in the container.PIHOLE_READ_ONLYExpose only inspection tools. Every tool that can change Pi-hole is hidden and rejected if called.PIHOLE_TLS_SKIP_VERIFYSet to true only for a Pi-hole serving a self-signed HTTPS certificate. A trusted certificate is the better fix.PIHOLE_REQUEST_TIMEOUTHTTP request timeout as a Go duration, e.g. 30s or 1mPIHOLE_MAX_RETRIESRetries after a transient Pi-hole API failure; 0 disables retryingPIHOLE_RETRY_MAX_DELAYUpper bound on a single exponential-backoff wait, as a Go duration
Tools this server provides (10)
Taken from the project documentation; the running server may differ.
- pihole_dns_get_blocking
- Reports whether DNS blocking is on and for how long.
- pihole_dns_set_blocking
- Turns blocking on or off, including timed pauses.
- pihole_search_domains
- Searches which lists contain a domain.
- pihole_stats_recent_blocked
- Shows recently blocked domains.
- pihole_local_dns_add
- Adds a local DNS record.
- pihole_lists_list
- Lists blocklists.
- pihole_network_devices
- Lists network devices Pi-hole has seen.
- pihole_instance_diff
- Compares two Pi-hole instances.
- pihole_teleporter_export
- Exports a configuration backup.
- pihole_stats_upstreams
- Shows upstream resolver statistics.
What it does
- 82 Pi-hole tools
- Covers domains, lists, groups, clients, DHCP, network, query log, config and local DNS.
- Read-only mode
- Exposes only inspection tools and rejects changes on every call.
- Toolset scoping
- Limits the server to chosen tool families to keep the surface small.
- Multi-instance diff and sync
- Compares two Pi-holes and reconciles with a dry-run plan and confirm token.
- Backup and restore
- Exports and restores configuration through Teleporter.
- Setup check
- A -check flag verifies each configured instance and flags affected FTL releases.
Good for
- Pause ad blocking for a few minutes while testing
- Work out why a site is blocked and which list caused it
- Review the most blocked domains for false positives
- Keep two Pi-holes in step
- Back up configuration before making changes
Pricing
Open source
Free and open source
Pi-hole MCP Server FAQ
What version of Pi-hole does it need?
Pi-hole v6, using its REST API.
Can I stop it from changing anything?
Yes. PIHOLE_READ_ONLY=true hides and rejects all tools that can change Pi-hole.
What credentials does it need?
The Pi-hole URL and an admin password or application password; the latter bypasses TOTP two-factor.
How is it distributed?
Homebrew, Scoop, go install, Docker, deb and rpm packages and release binaries.
Is Pi-hole MCP Server free?
Yes. Pi-hole MCP Server is open source, so you can use and self-host it for free.
How do I add Pi-hole MCP Server to Claude Code?
Run this command in your terminal: claude mcp add pihole-mcp --env PIHOLE_URL='<PIHOLE_URL>' --env PIHOLE_PASSWORD='<PIHOLE_PASSWORD>' -- docker run -i --rm -e PIHOLE_URL -e PIHOLE_PASSWORD ghcr.io/hexamatic/pihole-mcp:0.10.0
What are the best alternatives to Pi-hole MCP Server?
The closest alternatives to Pi-hole MCP Server are REA, Agent Roast, Midplane, Leash and Tinplate Edge AI Safety, Security & EU Compliance.
Alternatives to Pi-hole MCP Server

REA
MCP serverCLI and MCP server that lets coding agents reverse engineer apps and binaries
Runs locally- Open source
- 464K GitHub stars
- Developer tools
Agent Roast
MCP serverOffline review that flags agent changes which weaken tests, assertions or CI
Runs locally- Open source
- 4 Hacker News points
- Developer tools

Midplane
MCP serverPostgres gateway for AI agents with table grants, column masking and approval for writes
Runs locally- Open source
- 5 GitHub stars
- Databases

Leash
MCP serverReview what your AI touched, approve risky actions and undo supported changes
- 1 tool
- Remote
- Free
- 1 GitHub star
- Security
Zero-log MCP server with 49 tools for AI guardrails, secret scanning and EU compliance
- 49 tools
- Remote
- Freemium
- Security

SecureCloud
MCP serverSentinelOne and IT security catalog, prices, quotes and checkout links for Israel
- 7 tools
- Remote
- Free
- Security