Pi-hole

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

Most tools accept optional parameters for controlling output:

- detail(minimal|normal|full) — Controls response depth. Default:normal. Useminimalfor one-line summaries,fullfor complete API data.
- format(text|csv) — Output format for tabular data. Default:text. CSV saves ~29% tokens. Available onpihole_domains_list,pihole_lists_list,pihole_clients_list,pihole_queries_search,pihole_network_devices,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_dhcp_leases, andpihole_config_properties.

Pre-built multi-step workflows for common tasks:

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://instanceslists them, andpihole://<instance>/statusandpihole://<instance>/summaryread a named one. The unprefixed URIs above always read the first-declared instance.

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

SSE is deprecated.The MCP specification superseded the HTTP+SSE transport with Streamable HTTP in the 2025-03-26 revision.-transport sseis kept for older clients and still receives security fixes, but new deployments should use-transport http. It will be removed once the clients that need it have moved on.

Thehttpandssetransports apply two security middlewares to every request, in line with the MCP 2025-11-25 spec's DNS-rebinding protection guidance. stdio is unaffected (single-process, single-user).

-

Origin and Host validation.Both headers must resolve to a host inPIHOLE_ALLOWED_ORIGINS(default loopback only). MissingOriginis allowed for non-browser MCP clients. Mismatches return HTTP 403. To expose pihole-mcp on a LAN, extend the allowlist:

export PIHOLE_ALLOWED_ORIGINS="localhost,127.0.0.1,](https://github.com/lloydmcl/pihole-mcp/blob/HEAD/docs/TOOLS.md)[::1],pihole-mcp.lan"

The literal*disables enforcement entirely — only use it if you're behind a reverse proxy doing its own access control.

Per-session rate limiting.A token bucket keyed byMcp-Session-Id(fallback to client IP) caps requests atPIHOLE_RATE_LIMITper minute (default120, burstmax(120/4, 30)). Throttled requests return HTTP 429 withRetry-After: 1.0disables.

# 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

Tracing is opt-in. SetOTEL_EXPORTER_OTLP_ENDPOINTto 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 — a little over 40% smaller:

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 fromOTEL_EXPORTER_OTLP_ENDPOINTbeing ignored.