MCP Pi-hole Server

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)

Terminal

npx mcp-pihole-server

Or install globally:

Terminal

npm install -g mcp-pihole-server

Option 2: Clone and Build

bash

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

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:

config.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:

config.json

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

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

Example Output

Code

╔════════════════════════════════════════════════════════════════════════════╗
║                         🛡️  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

bash

# 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 README

MCP Pi-hole Server

Why Use This?

Features

Prerequisites

Installation

Option 1: Install from npm (recommended)

Option 2: Clone and Build

Configuration

1. Get Your Pi-hole App Password

2. Configure Your MCP Client

For Claude Desktop

For Claude Code

Environment Variables

Usage Examples

View Statistics

Control Blocking

Manage Domain Lists

View Query Log

Visual Dashboards

Available Tools

Statistics

Blocking Control

Domain Management

Maintenance

ASCII Visualizations

Supported Tools

Usage

Example Output

Development

Troubleshooting

"PIHOLE_URL and PIHOLE_PASSWORD environment variables are required"

"Authentication failed"

"API request failed: 401"

Connection refused

Contributing

License

Links