MCP Pihole

🚀 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.

🚀 Quick Start

This MCP server allows seamless interaction between AI assistants such as Claude and your Pi - hole network - wide ad blocker. You can manage DNS blocking, view statistics, and control domain lists using natural language.

✨ Features

📦 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

📚 Documentation

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

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

💻 Usage Examples

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"

💻 Usage Examples

Basic Usage

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

Advanced Usage

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

🔧 Technical Details

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

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

⚠️ Important Note

• "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.

📄 License

This project is under the MIT License. See LICENSE for details.

Links

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

Contributing

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