mcp-pihole
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PIHOLE_URL | Yes | Base URL of your Pi-hole instance (e.g., http://192.168.0.160:8080) | |
| PIHOLE_PASSWORD | No | Web interface password. Omit or leave empty for passwordless instances. |
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": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_server_versionA | Return the installed version of the mcp-pihole server. |
| get_statusA | Get Pi-hole status summary. Returns blocking status, total queries today, blocked count, percentage blocked, domains on blocklist, clients seen, unique domains, cached and forwarded query counts. |
| get_top_domainsA | Get top queried domains. count: number of domains to return (max 100). blocked: if True, returns top blocked domains instead of top permitted. |
| get_top_clientsA | Get top DNS clients by query count. count: number of clients to return (max 100). blocked: if True, returns clients with most blocked queries. |
| get_queriesA | Get recent DNS queries. length: number of queries to return (max 100). cursor: database ID for cursor-based pagination. Pass the cursor value from a previous response to get the next page. |
| get_versionA | Get Pi-hole FTL version information. |
| get_listsA | Get all configured blocklists. Returns each list's URL, enabled/disabled status, comment, and groups. |
| add_listA | Add a blocklist by URL. address: URL of the blocklist (e.g., https://example.com/hosts.txt). comment: optional description. enabled: whether the list is active (default True). After adding, run update_gravity to apply changes. |
| remove_listA | Remove a blocklist by URL. address: exact URL of the blocklist to remove. After removing, run update_gravity to apply changes. |
| update_listA | Update a blocklist's enabled status or comment. address: exact URL of the blocklist to update. enabled: set True to enable, False to disable. comment: update the list's description. Only provided fields are changed. After changes, run update_gravity. |
| update_gravityA | Rebuild the gravity database. Required after adding, removing, or modifying blocklists for changes to take effect. Runs asynchronously on the Pi-hole server. |
| get_domainsB | Get configured domain entries. type: "allow" (whitelist) or "deny" (blacklist). kind: "exact" (exact match) or "regex" (regular expression). |
| add_domainB | Add a domain to the allow or deny list. domain: the domain or regex pattern to add. type: "allow" (whitelist) or "deny" (blacklist). kind: "exact" (exact domain match) or "regex" (regular expression). comment: optional description. |
| remove_domainB | Remove a domain from the allow or deny list. domain: the exact domain or regex pattern to remove. type: "allow" or "deny". kind: "exact" or "regex". |
| search_domainsA | Check if a domain is blocked and by which list. Searches gravity, antigravity, exact deny/allow, and regex deny/allow lists. Useful for troubleshooting why a domain is blocked or allowed. |
| get_blocking_statusA | Get current DNS blocking status. Returns whether blocking is enabled/disabled and any active timer. |
| set_blockingA | Enable or disable DNS blocking. enabled: True to enable, False to disable. timer: optional seconds before blocking auto-reverts. Example: set_blocking(False, 300) disables for 5 minutes. |
| get_dhcp_leasesA | Get current DHCP leases. Returns active leases with IP, MAC address, hostname, and expiry time. |
| restart_dnsA | Restart the Pi-hole DNS resolver. Use after configuration changes that require a DNS restart. |
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 19 tools
Each tool targets a distinct resource and action. The get_* tools retrieve different types of data (status, leases, domains, lists, queries, top clients, top domains, versions) with clear descriptions. Add/remove/update/set/restart/search all have non-overlapping purposes, avoiding ambiguity even between get_version and get_server_version.
All tool names follow a consistent verb_noun pattern in snake_case. Verbs like add, get, remove, restart, search, set, update are used uniformly. The naming is predictable and easy to understand, with only minor variation like 'update_gravity' fitting the pattern well.
With 19 tools, the server covers the full range of Pi-hole administration: domain and list management, blocking control, statistics, DHCP, version info, and DNS restart. The count is well-scoped for the domain; every tool serves a clear purpose without bloat or omission.
The tool surface covers most essential CRUD operations for domains and lists, blocking control, statistics, and DHCP. A minor gap is the lack of an update_domain tool to modify domain comments, which may require workarounds. Overall, the set is nearly complete for Pi-hole management.