MCP Pi-hole Server

An MCP (Model Context Protocol) server that connects AI assistants like Claude to your Pi-hole network-wide ad blocker. Manage DNS blocking, view statistics, control whitelists/blacklists, and more through natural language.

Why Use This?

If you're running Pi-hole on your network, this MCP server lets you:

• Monitor DNS traffic - View query statistics, top blocked domains, and client activity
• Control blocking - Enable/disable Pi-hole blocking instantly or with a timer
• Manage lists - Add or remove domains from whitelist and blacklist without opening the web UI
• View query logs - See recent DNS queries with detailed information
• Maintain your Pi-hole - Update gravity (blocklists) and flush DNS cache

Features

| Category | Tools | |----------|-------| | Statistics | Query totals, blocking percentage, top domains, top clients | | Blocking Control | Enable, disable (with optional timer), check status | | Domain Lists | Whitelist/blacklist CRUD operations | | Query Log | Recent DNS queries with client, status, response time | | Maintenance | Update gravity, flush cache | | Visualizations | ASCII art dashboards and bar charts with ANSI colors |

Prerequisites

• Node.js 18+
• Pi-hole v6 with API enabled
• Pi-hole app password (generated in Pi-hole settings)
• Network access to Pi-hole from your machine

Installation

Option 1: Install from npm (recommended)

npx mcp-pihole-server

Or install globally:

npm install -g mcp-pihole-server

Option 2: Clone and Build

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

Configuration

1. Get Your Pi-hole App Password

1. Open your Pi-hole web interface
2. Go to Settings > API
3. Generate a new app password
4. Copy the password (it's only shown once)

2. Configure Your MCP Client

For Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

For Claude Code

Add to ~/.claude.json:

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

Environment Variables

| Variable | Description | Example | |----------|-------------|---------| | PIHOLE_URL | Pi-hole web interface URL | http://pihole.local:8080 | | PIHOLE_PASSWORD | Pi-hole app password | Your app password from settings |

Usage Examples

Once configured, you can interact with Pi-hole through natural language:

View Statistics

"Show me Pi-hole stats"

"What are the top blocked domains?"

"Which clients are making the most queries?"

Control Blocking

"Is Pi-hole blocking enabled?"

"Disable Pi-hole for 5 minutes"

"Re-enable Pi-hole blocking"

Manage Domain Lists

"Add example.com to the whitelist"

"Block ads.trackersite.com"

"Show me all whitelisted domains"

View Query Log

"Show me the last 50 DNS queries"

"What domains has my phone been querying?"

Visual Dashboards

"Show me Pi-hole stats with visualize: true"

"Get top blocked domains with visualization"

Available Tools

Statistics

• pihole_get_stats - Get comprehensive Pi-hole statistics
• pihole_get_top_blocked - Get top blocked domains
• pihole_get_top_permitted - Get top permitted domains
• pihole_get_top_clients - Get top clients by query count
• pihole_get_query_log - Get recent DNS queries

Blocking Control

• pihole_get_blocking_status - Check if blocking is enabled
• pihole_enable_blocking - Enable DNS blocking
• pihole_disable_blocking - Disable blocking (optionally with timer)

Domain Management

• pihole_get_whitelist - List all whitelisted domains
• pihole_get_blacklist - List all blacklisted domains
• pihole_add_to_whitelist - Add domain to whitelist
• pihole_add_to_blacklist - Add domain to blacklist
• pihole_remove_from_whitelist - Remove domain from whitelist
• pihole_remove_from_blacklist - Remove domain from blacklist

Maintenance

• pihole_update_gravity - Update blocklists (gravity)
• pihole_flush_cache - Flush DNS cache

ASCII Visualizations

This server supports colorful ASCII art visualizations rendered directly in your terminal using ANSI escape codes.

Supported Tools

The following tools support the optional visualize: true parameter:

| Tool | Visualization | |------|---------------| | pihole_get_stats | Full dashboard with summary stats, top clients, blocked domains, and permitted domains | | pihole_get_top_blocked | Red bar chart of blocked domains | | pihole_get_top_permitted | Green bar chart of permitted domains | | pihole_get_top_clients | Blue bar chart of client activity |

Usage

Pass visualize: true to any supported tool:

{
  "name": "pihole_get_stats",
  "arguments": {
    "visualize": true
  }
}

When visualize is not set or false, tools return JSON data as usual.

Example Output

╔════════════════════════════════════════════════════════════════════════════╗
║                         🛡️  PI-HOLE DASHBOARD                          ║
╠════════════════════════════════════════════════════════════════════════════╣
║                                                                            ║
║ 📊 SUMMARY                                                                 ║
║ ────────────────────────────────────────────────────────────────────────── ║
║ Total Queries:      73K             Domains Blocked:    2.4M               ║
║ Blocked:            22K             Active Clients:     28                 ║
║ Block Rate:         29.7%           Total Clients:      115                ║
╠════════════════════════════════════════════════════════════════════════════╣
║ 🔝 TOP CLIENTS                                                             ║
║ ────────────────────────────────────────────────────────────────────────── ║
║ 192.168.1.52     ████████████████████████████████████████   28K (38%)      ║
║ 192.168.1.51     ███████████████████▋                       14K (19%)      ║
╚════════════════════════════════════════════════════════════════════════════╝

(Colors appear in terminals that support ANSI escape codes)

Development

# Run in development mode (auto-reloads)
npm run watch

# Build for production
npm run build

# Run the built version
node dist/index.js

Troubleshooting

"PIHOLE_URL and PIHOLE_PASSWORD environment variables are required"

Ensure both environment variables are set in your MCP config.

"Authentication failed"

Your app password is invalid or expired. Generate a new one from Pi-hole Settings > API.

"API request failed: 401"

Session expired. The server will automatically re-authenticate, but if issues persist, check your password.

Connection refused

Ensure Pi-hole is running and the URL is correct. Check that you can access the Pi-hole web interface from your machine.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Links

• Pi-hole
• Pi-hole Documentation
• Model Context Protocol
• MCP Specification