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)```bash
npx mcp-pihole-server
Or install globally:```bash
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
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````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:```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:```json
{
"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```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.
Links
- Pi-hole
- Pi-hole Documentation
- Model Context Protocol
- MCP Specification