MCP Pi-hole Server

You can connect an MCP client to your Pi-hole network-wide ad blocker to monitor DNS traffic, control blocking, manage domain lists, view logs, and perform maintenance all through natural language. This MCP server lets AI assistants interact with Pi-hole to simplify everyday administration and give you quick, actionable insights from your network.

How to use

You use an MCP client to talk to the Pi-hole MCP server by configuring a server entry that points to the local or remote MCP runtime. Once configured, you can ask for Pi-hole statistics, top blocked domains, active clients, and recent queries. You can also enable or disable blocking (optionally with a timer), manage white- and blacklists, update gravity, and flush the DNS cache. When you request visual dashboards, you’ll receive colorful ASCII visualizations in supported terminals.

How to install

Prerequisites you need before installing are Node.js version 18 or newer and access to a Pi-hole v6 instance with the API enabled. You also need a Pi-hole app password generated in Pi-hole settings and network access from your machine to the Pi-hole web interface.

Option 1: Install from npm (recommended) You can run the MCP server directly with npx or install it globally.

npx mcp-pihole-server

npm install -g mcp-pihole-server

Option 2: Clone and build If you prefer to build locally, clone the repository, install dependencies, and build the project.

git clone https://github.com/aplaceforallmystuff/mcp-pihole.git
cd mcp-pihole
npm install
npm run build

Configuration and usage notes

To connect your MCP client to Pi-hole, you specify the Pi-hole web URL and the app password generated in Pi-hole settings. The client configuration uses an MCP server entry with the command to run the MCP server locally and the environment variables for Pi-hole access.

Example client configuration for Claude Desktop and Claude Code uses the same runtime and environment values. You must replace the placeholders with your actual Pi-hole address and app password.

Maintenance and access controls

You can query Pi-hole statistics, enable or disable blocking (with an optional timer), and retrieve the query log. You can also update gravity to refresh blocklists and flush the DNS cache. Visual dashboards are available to render data as ASCII charts in terminals that support ANSI colors.

Security considerations

Protect your Pi-hole app password and limit access to the MCP client to trusted machines. Use a strong app password and ensure your Pi-hole API is secured. Regularly rotate the app password if you suspect it has been exposed.

Troubleshooting

If you encounter issues connecting to Pi-hole, verify that Pi-hole is running, the API is enabled, and the URL in your MCP client configuration is correct. If authentication fails, generate a new app password in Pi-hole Settings > API and update your client configuration.

Example MCP config (stdio)

{
  "mcpServers": {
    "pihole": {
      "type": "stdio",
      "name": "pihole",
      "command": "npx",
      "args": ["-y", "mcp-pihole-server"],
      "env": {
        "PIHOLE_URL": "http://your-pihole-address:8080",
        "PIHOLE_PASSWORD": "your-app-password"
      }
    }
  }
}

Available tools

pihole_get_stats

Get comprehensive Pi-hole statistics such as total queries, blocking rate, top domains, and top clients.

pihole_get_top_blocked

Retrieve the top blocked domains with counts and percentages.

pihole_get_top_permitted

Retrieve the top permitted domains with counts and percentages.

pihole_get_top_clients

List top clients by query count.

pihole_get_query_log

Fetch recent DNS queries with details like client, status, and response time.

pihole_get_blocking_status

Check whether Pi-hole blocking is enabled.

pihole_enable_blocking

Enable DNS blocking.

pihole_disable_blocking

Disable DNS blocking, with optional timer support.

pihole_get_whitelist

List all whitelisted domains.

pihole_get_blacklist

List all blacklisted domains.

pihole_add_to_whitelist

Add a domain to the whitelist.

pihole_add_to_blacklist

Add a domain to the blacklist.

pihole_remove_from_whitelist

Remove a domain from the whitelist.

pihole_remove_from_blacklist

Remove a domain from the blacklist.

pihole_update_gravity

Update blocklists (gravity).

pihole_flush_cache

Flush DNS cache.