pihole-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PIHOLE_URL | Yes | The URL of the Pi-hole server | |
| PIHOLE_PASSWORD | Yes | The application password for Pi-hole API authentication, created in the Pi-hole Web UI under Settings > Web Interface > 'Application password' > Generate |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| extensions | {
"io.modelcontextprotocol/ui": {}
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_statsA | Get summary statistics (total queries, blocked queries, blocking percentage, unique domains, clients). |
| get_top_blockedB | Get top blocked domains by query count. |
| get_top_permittedB | Get top allowed (permitted) domains by query count. |
| get_top_clientsA | Get top clients by query count. Set blocked=true for top clients by blocked query count. |
| get_query_typesB | Breakdown of DNS query types (A, AAAA, PTR, SRV, etc). |
| get_forward_destinationsA | Upstream DNS server stats (which forwarders served how many queries). |
| get_recent_blockedC | Recently blocked domains. |
| get_historyA | Time-series activity graph: timestamps, allowed/blocked/other counts per bucket. |
| get_query_logA | Fetch recent DNS queries with optional filters. Filters:
|
| get_query_suggestionsA | Get available filter values for the query log (domains, clients, upstreams, types, statuses). |
| get_blocking_statusA | Check if Pi-hole DNS blocking is enabled. Returns status and any active timer. |
| enable_blockingA | Enable DNS blocking immediately. |
| disable_blockingA | Disable DNS blocking. If duration_seconds is given, re-enables after that timer; otherwise indefinite. |
| get_whitelistA | List all exact-match allowed domains. |
| get_blacklistA | List all exact-match blocked domains. |
| add_to_whitelistC | Add a domain to the allow list (whitelist). |
| add_to_blacklistC | Add a domain to the deny list (blacklist). |
| remove_from_whitelistB | Remove a domain from the allow list. |
| remove_from_blacklistB | Remove a domain from the deny list. |
| list_local_dnsA | List local DNS entries (hosts and CNAME records). |
| add_local_a_recordA | Add a local A record (host -> IP). Replaces any existing entry for the same host. |
| remove_local_a_recordB | Remove any local A record matching the given host. |
| add_local_cname_recordA | Add a local CNAME record (host -> target). Replaces any existing CNAME for the same host. |
| remove_local_cname_recordB | Remove any local CNAME record for the given host. |
| update_gravityA | Refresh Pi-hole gravity (adlist database). Takes a minute or more to complete. |
| flush_cacheA | Flush the Pi-hole DNS cache. |
| flush_logsA | Clear the Pi-hole query log. |
| get_tail_logC | Get the tail of a Pi-hole log file. log must be one of 'dnsmasq', 'ftl', 'webserver'. |
| server_infoA | Return chris2ao-pihole-mcp server version, configured Pi-hole URL, and tool count. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 29 tools
Each tool has a distinct purpose: blocking management, local DNS, query logs, stats, etc. No two tools are ambiguously similar; descriptions clearly differentiate them.
The vast majority use a clear verb_noun pattern (e.g., add_to_blacklist, get_stats). The sole exception (server_info) is a minor deviation but still understandable.
29 tools is slightly above the typical well-scoped range, but the Pi-hole domain has many facets, so each tool serves a specific need. Could be reduced by combining some get_top_* tools, but still reasonable.
Covers core CRUD for blacklist/whitelist and local DNS, plus extensive query and stats tools. Missing administrative settings or group management, but the surface covers common use cases without dead ends.