Pi-hole MCP Server

List Pi-hole config keys that are read-only — set via pihole.toml or env var, not modifiable through the API. Use after a pihole_config_set error to confirm whether a key is intentionally locked.

Remove a value from a configuration array such as dns.upstreams. For dns.hosts and dns.cnameRecords prefer pihole_local_dns_delete and pihole_local_cname_delete, which take structured arguments.

Modify Pi-hole configuration. Provide nested JSON properties to change. Changes take effect immediately and can affect DNS behaviour system-wide.

Remove an active DHCP lease by IP address. Only works when Pi-hole's DHCP server is enabled.

Active DHCP leases: IP, hostname, MAC address, and expiry, paged with limit/offset. Empty if Pi-hole's DHCP server is disabled.

Get the current DNS blocking status and any active timer for temporary blocking changes.

Enable or disable DNS blocking. Set a timer (seconds) to automatically revert after a duration.

Add domains to an allow or deny list. Supports bulk add via comma-separated domains. Use pihole_search_domains first to avoid duplicates.

Remove multiple domains at once. Each item needs domain, type (allow/deny), and kind (exact/regex).

Remove a domain from an allow or deny list. Requires the exact type, kind, and domain.

List domains on allow/deny lists. Filter by type (allow/deny) and kind (exact/regex), page with limit/offset. Use pihole_search_domains for cross-list search.

Update a domain entry's comment or enabled status. Changing type or kind creates a duplicate rather than moving the entry; delete the original separately if that is what you want.

Create a group for organising domains and clients into sets with independent blocking rules.

Delete multiple groups at once. Provide a JSON array of group names.

Delete a group by name. Domains and clients assigned to this group lose the association.

List groups used for organising domains and clients into sets with independent blocking rules. Page with limit/offset.

Update or rename a group. Changing the name updates all associated domain and client references.

In-memory per-client query activity (FTL memory, last ~24h), busiest client first. detail=full returns the per-slot time series. For arbitrary date ranges, use pihole_history_database_clients.

Long-term query activity from the FTL database as a time series: one bucket per slot across the range. Use pihole_stats_database instead for a single set of totals over the whole range.

Long-term per-client query activity from the FTL database (durable, arbitrary date range), busiest client first. detail=full returns the per-slot time series.

In-memory query activity (FTL memory, last ~24h): total/cached/blocked/forwarded per time slot. detail=full or format=csv returns every slot. For arbitrary date ranges, use pihole_history_database.

Information about the requesting client's IP address and connection. Does not require authentication.

Query database details: file size, total stored queries, SQLite version, and how far back the stored queries reach.

Dismiss an FTL diagnostic message by ID, clearing it from Pi-hole. Get IDs from pihole_info_messages.

FTL engine process info: PID, privacy level, client and domain counts, and database query total.

FTL diagnostic messages — warnings about DNS resolution failures, database issues, or configuration problems.

Live DNS and DHCP operational metrics as dotted key/value lines: cache size, inserts, evictions, reply counts and lease statistics.

Hardware temperature sensors with names, values, units, and paths.

System health: hostname, OS, CPU/memory/disk usage, load averages, temperature, and DNS service status.

Pi-hole component versions: core, FTL engine, web interface, and Docker tag if applicable.

Compare configuration between two Pi-hole instances (adlists, allow/deny rules, groups, clients, local DNS). Read-only — reports what a sync would change.

Reconcile a target Pi-hole towards a source. Runs as a dry-run plan by default; re-call with mode=apply and the returned confirm_token to apply. Pushes one direction only (source to target).

Subscribe to a new blocklist or allowlist URL. Run pihole_action_gravity_update afterwards to download it.

Unsubscribe from multiple lists at once. Each item needs URL and type (allow/block).

Unsubscribe from a blocklist or allowlist. Run pihole_action_gravity_update afterwards to apply changes.

List configured blocklists and allowlists with domain counts and update status. Filter by type (allow/block), page with limit/offset.

Update a blocklist or allowlist entry's comment or enabled status.

Add a local CNAME record pointing an alias at another name. The target must be a name Pi-hole can already resolve.

Delete a local CNAME record by its alias. Pi-hole stops resolving that alias.

List local CNAME records from dns.cnameRecords. Each record points an alias at another name this Pi-hole can resolve.

Add a local A or AAAA record, so this Pi-hole resolves a hostname to an IP address. The record type follows from the address family.

Delete a local A or AAAA record by IP address and hostname. Pi-hole stops resolving that hostname locally.

List local A and AAAA records this Pi-hole answers for, from dns.hosts. Each record maps an IP address to a hostname.

Permanently delete a network device record by ID. Use pihole_network_devices first to find the ID. Devices may reappear if active on the network.

Devices seen on the network: MAC, IPs, hostnames, vendor, query count, and first/last seen timestamps. Returns 20 by default.

Network gateway details: address, interface, address family, and local interface IPs.

Lightweight summary of routing table and interface state. For detailed per-route or per-interface data, use pihole_network_routes or pihole_network_interfaces.

Network interfaces with addresses, link state, speed, and traffic counters.

System routing table entries with family, scope, source, destination, gateway, and outbound interface.

One-call dashboard: queries, blocking, top domain/client, cache, versions, and host health. Best starting point for a status overview.

Search DNS query log with filters by domain, client, type, status, and time range. Returns 25 most recent by default with cursor pagination. Set disk=true to search the long-term database for anything older than FTL's in-memory window.

Available filter values for pihole_queries_search: known domains, client addresses and names, upstreams, query types, statuses, reply types and DNSSEC states.

Search for a domain across all allow/deny lists and gravity blocklists. Use before modifying lists to check current state.

Long-term database statistics aggregated over a time range: one set of totals for queries, blocked and clients. Use pihole_history_database for the same range broken into time slots.

Historical distribution of DNS query types (A, AAAA, MX, etc.) for a date range.

Most active clients from the long-term database for a date range. Use blocked=true for clients with most blocked queries.

Top queried or blocked domains from the long-term database for a date range. Returns 10 by default, max 50.

Historical upstream DNS server performance for a date range: query counts and average response times.

Distribution of DNS query types (A, AAAA, MX, PTR, HTTPS, etc.) with counts.

Most recently blocked domains — useful for spotting new tracking domains or false positives in real-time.

Overview of Pi-hole activity: queries, blocking rate, active clients, gravity size, and top query types. Start here for a health check.

Most active network clients ranked by query count. Use blocked=true for clients with most blocked queries.

Top queried or top blocked domains ranked by count. Returns 10 by default, max 50.

Upstream DNS server performance: query counts, average response time, and standard deviation per server.

Export a full Pi-hole configuration backup as a zip archive. Returns the saved file path and size. The file persists on disk after the call returns and is the caller's to move or delete; under Docker it is written inside the container unless output_path points at a mounted volume.

Import a Pi-hole configuration backup from a zip archive. Selectively import config, gravity tables, and DHCP leases.