MCP Pi-hole Server

![npm version](https://www.npmjs.com/package/mcp-pihole-server) ![CI](https://github.com/aplaceforallmystuff/mcp-pihole/actions/workflows/ci.yml) ![License: MIT](https://opensource.org/licenses/MIT) ![MCP](https://modelcontextprotocol.io)

!Architecture

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

Open your Pi-hole web interface
Go to Settings > API
Generate a new app password
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.

mcp-pihole