Building an MCP Server for Pi-hole: Network Ad Blocking Through Natural Language

I run Pi-hole on a Raspberry Pi for network-wide ad blocking. It handles DNS for every device on my network, blocking ads and trackers before they even load. The web interface is fine for checking stats or managing domain lists, but it’s another tab to open when I’m working with Claude.

So I built mcp-pihole—an MCP server that lets me manage Pi-hole through natural language conversation.

The Problem With Another Dashboard

Here’s a typical workflow before mcp-pihole:

1. I’m working with Claude

2. Something isn’t loading, might be Pi-hole blocking it

3. I open the Pi-hole dashboard in a new tab

4. I log in

5. I check the query log or add a domain to the whitelist

6. I switch back to Claude

With mcp-pihole, that becomes:

1. “Add example.com to the whitelist”

2. Done

Or:

1. “Disable Pi-hole for 5 minutes”

2. Test the thing

3. Blocking re-enables automatically

What You Can Do

The server provides 16 tools covering Pi-hole administration:

Statistics:

• “Show me Pi-hole stats”

• “What are the top blocked domains?”

• “Which clients are making the most queries?”

• “Show me the last 50 DNS queries”

Blocking Control:

• “Is Pi-hole blocking enabled?”

• “Disable Pi-hole for 5 minutes”

• “Re-enable Pi-hole blocking”

Domain Management:

• “Add example.com to the whitelist”

• “Block ads.trackersite.com”

• “Show me all whitelisted domains”

• “Remove example.com from the blacklist”

Maintenance:

• “Update gravity (blocklists)”

• “Flush the DNS cache”

The Complete Tool List

Category	Tools
Statistics	get_stats, get_top_blocked, get_top_permitted, get_top_clients, get_query_log
Blocking	get_blocking_status, enable_blocking, disable_blocking
Whitelist	get_whitelist, add_to_whitelist, remove_from_whitelist
Blacklist	get_blacklist, add_to_blacklist, remove_from_blacklist
Maintenance	update_gravity, flush_cache

Configuration

You need two environment variables—the Pi-hole URL and an app password:

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

Get the app password from Pi-hole’s Settings > API page. This is for Pi-hole v6—the authentication model changed from earlier versions.

Get It

npm: mcp-pihole-server — Install with npx mcp-pihole-server, add your credentials, and you’re running.

Learn More About Pi-hole and MCP

These videos provide excellent tutorials on setting up Pi-hole and understanding the Model Context Protocol:

World’s Greatest Pi-hole Tutorial - Complete setup guide for installing Pi-hole on Raspberry Pi:

https://www.youtube.com/watch?v=cE21YjuaB6o

MCP In 26 Minutes - Comprehensive tutorial covering MCP fundamentals and how to build MCP servers:

https://www.youtube.com/watch?v=kOhLoixrJXo