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