pihole-mcp

A production-grade MCP server for Pi-hole v6.

82 tools (84 with a second instance) | 9 prompts | 5 resources | Multi-instance + sync | Read-only mode + toolsets | Single Go binary

OpenSSF Scorecard

Gives AI assistants full control over your Pi-hole instance: DNS blocking, domain management, query analysis, statistics, network devices, DHCP, and system administration. Compatible with the Pi-hole v6 REST API.

Why this one

• Run it locked down. PIHOLE_READ_ONLY=true exposes only the tools that cannot change anything, enforced on every call, not just the tool list a client happens to cache. PIHOLE_TOOLSETS narrows further to just the families you need, so a client asking "what can I use" gets a smaller, cheaper answer.
• 82 tools (84 once a second Pi-hole is configured) covering roughly 95% of the Pi-hole v6 REST API, including domains, lists, groups, clients, DHCP, network, the query log, configuration, local DNS records, teleporter backup and restore, and session management.
• Multi-instance diff and sync. Compare two Pi-holes and see exactly what differs, or reconcile one onto the other with a dry-run plan and a confirm token before anything is written.
• Releases are signed and attested, not just built. Every archive and container image carries a keyless cosign signature, an SPDX SBOM and SLSA build provenance, and SECURITY.md has the one-line command to check each.
• Listed in the official MCP Registry as io.github.hexamatic/pihole-mcp, installable by name from any client that supports registry install.
• Shipped nine releases in five months since launch, each with real release notes describing what changed and why, not a commit-hash dump.

Quick Start

Most MCP clients use the same configuration format. Add this to your client's config:

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

Then install the binary via one of the methods below.

What you can ask

The whole point is natural language, not tool names. A few examples of what to actually type:

Set PIHOLE_READ_ONLY=true first if you want to ask questions without any risk of something being changed. See Scoping the tool surface.

Installation

MCP Registry

pihole-mcp is listed in the official MCP Registry as:

io.github.hexamatic/pihole-mcp

Clients that support registry install can add it by that name and will prompt for PIHOLE_URL and PIHOLE_PASSWORD. The listing points at the ghcr.io image, so the client needs a working Docker.

Homebrew

brew install hexamatic/tap/pihole-mcp

Installs on both macOS and Linux (Homebrew on Linux). On macOS the cask clears the quarantine attribute during install, so the binary runs without a Gatekeeper prompt.

Scoop (Windows)

scoop bucket add hexamatic https://github.com/hexamatic/scoop-bucket
scoop install pihole-mcp

Go Install

go install github.com/hexamatic/pihole-mcp/cmd/pihole-mcp@latest

Docker

docker pull ghcr.io/hexamatic/pihole-mcp:latest

Linux Packages

.deb and .rpm packages for Debian-based (Ubuntu, Raspberry Pi OS) and RPM-based (Fedora, RHEL) distributions are available on the Releases page.

# Debian / Ubuntu / Raspberry Pi OS
sudo dpkg -i pihole-mcp_X.Y.Z_linux_amd64.deb

# Fedora / RHEL / CentOS
sudo rpm -i pihole-mcp_X.Y.Z_linux_amd64.rpm

Binary Download

Pre-built binaries for Linux, macOS, and Windows (amd64 and arm64) are available on the Releases page.

Releases are checksummed, signed with keyless cosign, and ship SPDX SBOMs and SLSA build provenance. See SECURITY.md for the verification commands.

Check your setup

Once installed and configured, run the server directly with -check. It loads the configuration, contacts every Pi-hole you have configured, and reports each one by name:

PIHOLE_URL=http://192.168.1.2 PIHOLE_PASSWORD=your-password pihole-mcp -check

pihole-mcp 0.9.0

PASS  primary (http://192.168.1.2)  core v6.1.4, FTL v6.7

All 1 instance(s) reachable and authenticated.

It exits non-zero if any instance fails, and prints what to change. Worth running before you wire the server into a client: most clients hide the server's output, so a bad URL or password looks the same as a server that never started.

Configuration

Application passwords are recommended for automation: they bypass TOTP 2FA and can be revoked independently.

PIHOLE_HTTP_AUTH_TOKEN, PIHOLE_HTTP_AUTH_TOKEN_FILE, PIHOLE_RATE_LIMIT, PIHOLE_ALLOWED_ORIGINS and PIHOLE_TRUSTED_PROXIES only apply to the http and sse transports; stdio is a single-process, single-user channel by definition and isn't gated. See Security before exposing either transport beyond loopback.

Scoping the tool surface

By default the server offers every tool, including 34 that change Pi-hole and 27 that are destructive. Two variables narrow that.

PIHOLE_READ_ONLY=true exposes only tools that cannot change anything. Write tools are absent from tools/list and rejected if called anyway, so a client working from a cached listing cannot reach one either.

PIHOLE_READ_ONLY=true    # 49 tools instead of 82

PIHOLE_TOOLSETS selects which families of tools exist at all, which is worth doing on its own because tools/list is a cost paid in every conversation:

PIHOLE_TOOLSETS=dashboard,domains,lists    # blocklist curation, and nothing else
PIHOLE_TOOLSETS=all                        # the default, stated explicitly

The two intersect, and read-only always wins. PIHOLE_READ_ONLY=true with PIHOLE_TOOLSETS=dns,stats gives the 14 tools that are in those toolsets and read-only.

The toolset names, what each contains and how many tools it holds are in docs/TOOLS.md, generated from the same table the server filters with. An unknown name fails at startup and lists every valid one; run pihole-mcp -check to see it, along with how many tools your configuration actually exposes:

scope: read-only=true, toolsets=dns,stats  14 of 82 tools exposed

A published toolset name is never removed, renamed or narrowed. See CONTRIBUTING.md for the full promise.

Multiple instances

To manage more than one Pi-hole, configure numbered instances instead of PIHOLE_URL/PIHOLE_PASSWORD:

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_1_URL": "http://192.168.1.2",
        "PIHOLE_1_PASSWORD": "primary-password",
        "PIHOLE_1_NAME": "downstairs",
        "PIHOLE_2_URL": "http://192.168.1.3",
        "PIHOLE_2_PASSWORD": "secondary-password",
        "PIHOLE_2_NAME": "upstairs"
      }
    }
  }
}

Every tool then accepts an optional instance argument, and every result is labelled with the instance it came from. Omit the argument to target the first instance; pass a name to target a specific one; pass instance=all on a read-only tool (e.g. pihole_padd, pihole_stats_summary) to query every instance concurrently and get back a single structured aggregate (per-instance results plus a success/failure summary, so one slow or unreachable instance no longer fails the whole call). State-changing tools require a single named instance. PIHOLE_URL and PIHOLE_1_URL are mutually exclusive.

Keeping instances in sync

When you run more than one Pi-hole, two extra tools appear for keeping them aligned:

• pihole_instance_diff: compare two instances and see exactly what differs across adlists/allowlists, allow/deny rules (exact and regex), groups, clients, local DNS A/AAAA records, and CNAME records. It is read-only and writes nothing.
• pihole_instance_sync: push a source instance's configuration onto a target. It is deliberately cautious:
  • One direction only. You name the source of truth and the target; only the target is ever written to.
  • Dry-run first. It returns a plan and a confirm_token by default; nothing changes until you re-run with mode=apply and that token. If the configuration drifts between planning and applying, the token no longer matches and the apply is refused.
  • Add/update by default. Entries on the target but not the source are left alone unless you pass prune=true.
  • Backed up. A teleporter backup of the target is taken before any change (disable with snapshot=false).
  • Safe by omission. Host-specific and identity settings (DHCP, interface bindings, passwords, TLS certificates, sessions, 2FA) are never synced. Group membership associations are not synced either, because Pi-hole group IDs are local to each instance.

Example: preview what the upstairs Pi-hole is missing relative to downstairs, then apply it.

pihole_instance_diff   { "source": "downstairs", "target": "upstairs" }
pihole_instance_sync   { "source": "downstairs", "target": "upstairs" }            → returns a plan + confirm_token
pihole_instance_sync   { "source": "downstairs", "target": "upstairs",
                         "mode": "apply", "confirm_token": "<token from the plan>" }

Client Setup

The Quick Start config above works for most clients. Expand the section below for client-specific instructions.

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

claude mcp add pihole \
  -e PIHOLE_URL=http://192.168.1.2 \
  -e PIHOLE_PASSWORD=your-password \
  -- pihole-mcp

claude mcp list

{
  "servers": {
    "pihole": {
      "type": "stdio",
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PIHOLE_URL=http://192.168.1.2",
        "-e", "PIHOLE_PASSWORD=your-password",
        "-e", "TZ=Australia/Adelaide",
        "-v", "/host/path/for/backups:/backups",
        "ghcr.io/hexamatic/pihole-mcp:latest"]
    }
  }
}

docker run --rm \
  -e PIHOLE_URL=http://192.168.1.2 \
  -e PIHOLE_PASSWORD=your-password \
  ghcr.io/hexamatic/pihole-mcp:latest -check

Tools

A single Pi-hole exposes 82 tools. Configuring more than one adds pihole_instance_diff and pihole_instance_sync, for 84. Those two are registered only when there is a second instance to compare against, so a single-Pi-hole setup isn't shown tools it cannot use.

To expose fewer, see Scoping the tool surface.

The tables below are a summary; the full generated reference with every parameter is in docs/TOOLS.md.

Dashboard

DNS Control

Local DNS

Statistics

Domain Management

Groups, Clients, Lists

Query Log

System

Actions and Network

Multi-instance (only with more than one Pi-hole configured)

Response Options

Some tools accept optional parameters for controlling output:

• detail (minimal | normal | full): controls response depth. Default: normal. Use minimal for one-line summaries, full for complete API data. Available on 15 tools.
• format (text | csv): output format for tabular data. Default: text. CSV saves roughly 8–23% tokens over the default text rendering, depending on the tool and row count. Available on 22 tools: pihole_domains_list, pihole_groups_list, pihole_lists_list, pihole_clients_list, pihole_queries_search, pihole_network_devices, pihole_dhcp_leases, pihole_config_properties, pihole_local_dns_list, pihole_local_cname_list, pihole_stats_top_domains, pihole_stats_top_clients, pihole_stats_upstreams, pihole_stats_query_types, pihole_stats_recent_blocked, pihole_stats_database_top_domains, pihole_stats_database_top_clients, pihole_stats_database_upstreams, pihole_history_graph, pihole_history_clients, pihole_history_database, and pihole_history_database_clients.

Prompts

Pre-built multi-step workflows for common tasks:

Resources

Read-only context an MCP client can pull in without calling a tool:

With more than one Pi-hole configured, each instance is also addressable directly: pihole://instances lists them, and pihole://<instance>/status and pihole://<instance>/summary read a named one. The unprefixed URIs above always read the first-declared instance.

Advanced Configuration

Transport

By default, pihole-mcp uses stdio (standard for MCP). HTTP and SSE transports are also available:

# Default stdio (for Claude Desktop, Cursor, etc.)
pihole-mcp

# HTTP transport (for web-based MCP clients)
pihole-mcp -transport http -address localhost:8080

# SSE transport (deprecated, see below)
pihole-mcp -transport sse -address localhost:8080

Both examples bind loopback, so only this machine can reach them. Before changing that, read Security below: neither transport authenticates anything until you configure a token.

pihole-mcp implements MCP protocol revision 2025-11-25 and negotiates down for older clients (2025-06-18, 2025-03-26 and 2024-11-05 are all accepted).

SSE is deprecated. The HTTP+SSE transport was superseded by Streamable HTTP in the 2025-03-26 revision, and formally reclassified as Deprecated under the specification's feature lifecycle policy (SEP-2596), meaning it stays part of the spec, fully supported, for a minimum of twelve months before removal could even be proposed. -transport sse is kept for older clients and still receives security fixes, but new deployments should use -transport http.

Security (HTTP and SSE transports)

The http and sse transports have no authentication until you configure one. stdio is unaffected: it is a single-process, single-user channel by definition.

The default listen address is localhost:8080, so out of the box only this machine can reach the server. Change the bind address without setting a token and anyone who can reach the port can control your Pi-hole: disable blocking, rewrite your blocklists, read every DNS query on the network.

• Bearer authentication (recommended whenever the bind address is not loopback). Set a shared token and every request must carry it in an Authorization: Bearer header. Requests without it are answered 401 before anything else runs. Tokens must be at least 16 characters.

  bash

  export PIHOLE_HTTP_AUTH_TOKEN="$(openssl rand -base64 32)"
  # A bind beyond loopback needs the allowlist extended too, or clients reach a
  # 403 from the Host check before the token is ever looked at.
  export PIHOLE_ALLOWED_ORIGINS="localhost,127.0.0.1,[::1],192.168.1.10"
  pihole-mcp -transport http -address 0.0.0.0:8080
  

  An environment variable set on a command line is visible in ps to every user on the host, so the token can be read from a file instead. This is also the shape container platforms mount secrets in:

  bash

  export PIHOLE_HTTP_AUTH_TOKEN_FILE=/run/secrets/pihole-mcp-token
  

  Set one or the other, not both. The token is compared in constant time, so a wrong token tells an attacker nothing about how much of it was right. Rejected requests are charged to a separate failed-authentication budget of roughly twenty attempts per address and then one a second, so the token cannot be guessed at line rate, a flood of wrong tokens cannot starve a client at the same address that does hold it, and the server logs the throttling once rather than once per attempt.

  Binding a non-loopback address with no token logs an error at startup and carries on. It does not refuse to start, because putting a reverse proxy that authenticates in front of it is a legitimate deployment.

• Origin and Host validation. Both headers must resolve to a host in PIHOLE_ALLOWED_ORIGINS (default loopback only). Mismatches return 403. Missing Origin is allowed, because non-browser MCP clients do not send one.

  This is not authentication. It is DNS-rebinding protection, and it only protects browsers: a page a victim visits cannot make their browser attach an Origin the allowlist accepts. Both headers are chosen by the caller, so any client that is not a browser sets them to whatever the allowlist wants. Use PIHOLE_HTTP_AUTH_TOKEN for access control.

  bash

  export PIHOLE_ALLOWED_ORIGINS="localhost,127.0.0.1,[::1],pihole-mcp.lan"
  

  The literal * disables enforcement entirely. That is reasonable behind a reverse proxy, or with a bearer token set, and not otherwise.

• Rate limiting. A token bucket per client address, with a second bucket per MCP session underneath it. PIHOLE_RATE_LIMIT (default 120, burst max(120/4, 30)) is the per-session rate; one address may send four times that. Throttled requests return 429 with Retry-After: 1. 0 disables.

  The address ceiling is what actually bounds a caller, because Mcp-Session-Id is a header the client writes: without a ceiling, a caller sending a fresh session id on every request would never be limited at all. The header is also being removed from the transport in MCP revision 2026-07-28, after which the ceiling is the whole limiter. Every request is charged to the ceiling first, including one the session bucket then rejects, so a client that is already being throttled keeps drawing on the budget its neighbours share. IPv6 clients are counted per /64, since a single host is routinely given a whole one.

  bash

  # Tighter limit for a small fleet
  export PIHOLE_RATE_LIMIT=60
  
  # Disable (only when running behind a proxy with its own rate limit)
  export PIHOLE_RATE_LIMIT=0
  

• Behind a reverse proxy. By default the client address is the connection's peer address, which behind a proxy is the proxy itself, so every client through it shares one ceiling. Name the proxy networks and X-Forwarded-For is used instead, taking the rightmost entry that is not itself a listed proxy:

  bash

  export PIHOLE_TRUSTED_PROXIES="192.168.1.5"
  

  Nothing is trusted by default, deliberately: X-Forwarded-For is client-supplied, so a server that believes it unconditionally lets any caller pick its own rate-limit bucket. Every host inside a prefix you list gets that power, so name the individual proxies where you can and keep any CIDR block as tight as the deployment allows. 10.0.0.0/8 trusts your whole network.

OpenTelemetry

Tracing is opt-in. Set OTEL_EXPORTER_OTLP_ENDPOINT to enable:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
pihole-mcp

All tool calls are automatically traced with tool name, duration, and error status.

If you don't need tracing, the slim build strips the OpenTelemetry SDK, gRPC, protobuf and grpc-gateway dependencies entirely. The binary is 43% smaller:

Measured from the v0.9.0 release assets. MB here is a million bytes, and the image figure is the unpacked size docker images reports for the linux/arm64 image, the one a Raspberry Pi pulls.

just build-slim
# or
go build -tags slim -o bin/pihole-mcp-slim ./cmd/pihole-mcp

# Docker
docker pull ghcr.io/hexamatic/pihole-mcp:latest-slim

The slim binary is functionally identical apart from OTEL_EXPORTER_OTLP_ENDPOINT being ignored.

Troubleshooting

"Pi-hole rejected the login: its API session pool is full"

Pi-hole allows a limited number of concurrent API sessions (webserver.api.max_sessions, 16 by default), and every client that logs in takes a seat: the web interface, PADD, Home Assistant, any other integration, and pihole-mcp. When they are all taken, Pi-hole answers 429 and refuses further logins, including from its own web interface.

pihole-mcp releases its seat on shutdown, but a session left behind by a process that was killed rather than stopped will hold one until it expires. Three ways out, in order of preference:

1. Free a seat. Ask for the session list (pihole_auth_sessions) and revoke one that is idle (pihole_auth_revoke_session).
2. Raise the cap. On a machine with a handful of integrations, 16 is low:
   bash

   pihole-FTL --config webserver.api.max_sessions 32
   

3. Wait. Seats release themselves after webserver.session.timeout (30 minutes by default).

Retrying will not help, so pihole-mcp does not: it reports the problem instead of silently stalling.

Authentication fails with a correct password

Pi-hole rate-limits repeated failed logins, and the limiter does not distinguish between "wrong password" and "the password you just fixed". Wait a few seconds and try again. If it persists, confirm you are using the admin password or an application password, not the web interface's TOTP code.

Docker: "connection refused" reaching Pi-hole

localhost inside a container is the container, not the host. Point PIHOLE_URL at the host's LAN address (http://192.168.1.2), at host.docker.internal on Docker Desktop, or put both containers on the same Docker network and use the Pi-hole container's name.

Timestamps are shown in UTC

Every timestamp in tool output carries an explicit zone marker (e.g. 19 Jul 2026, 9:41 AM UTC), so responses are unambiguous whatever the zone. Which zone is used depends on where the server runs: native binaries use the system timezone, while the Docker image defaults to UTC. To get local times from the container, set TZ on the pihole-mcp container (not just the Pi-hole one). Timezone data is embedded in the binary, so no extra packages or volume mounts are needed:

environment:
  - TZ=Australia/Adelaide

An unrecognised TZ value logs a warning at startup and falls back to UTC rather than refusing to start.

"x509: certificate signed by unknown authority"

Your Pi-hole is serving HTTPS with a self-signed certificate, which fails standard TLS verification. The right fix is a trusted certificate on the Pi-hole (for example via its built-in domain settings or a reverse proxy with Let's Encrypt). If that isn't practical, set PIHOLE_TLS_SKIP_VERIFY=true to disable verification. Connections are still encrypted, but the server's identity is no longer checked, so only use this on a network you control.

Occasional dropped connections

Pi-hole's embedded web server closes connections under load. pihole-mcp retries these automatically with backoff; if you see failures anyway, raise PIHOLE_MAX_RETRIES (default 3).

Getting help

• Usage question? Ask in Q&A Discussions; someone with the same question later will find the answer there.
• Found a bug, or want a feature? Open an issue.
• Security vulnerability? See SECURITY.md. Please don't open a public issue.

See SUPPORT.md for the full picture, including where to start contributing.

Development

# Prerequisites: Go 1.26+, Docker, mise, just

# One-command setup
just setup

# Start local Pi-hole (http://localhost:8081, password: test)
# Port already taken? PIHOLE_DEV_PORT=8091 just dev-up
just dev-up

# Run quality checks (format + lint + test)
just check

# Run integration tests against local Pi-hole
just integration

# Build binary
just build

See CONTRIBUTING.md for full development guidelines.

Pi-hole is a registered trademark of Pi-hole LLC. This project is independently maintained and is not affiliated with, endorsed by, or sponsored by Pi-hole LLC.

Licence

MIT