# MCP Pi-hole Server

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

![Architecture](docs/images/architecture-diagram.png)

An MCP (Model Context Protocol) server that connects AI assistants like Claude to your [Pi-hole](https://pi-hole.net) 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](https://pi-hole.net) 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](CONTRIBUTING.md) for guidelines.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Links

- [Pi-hole](https://pi-hole.net)
- [Pi-hole Documentation](https://docs.pi-hole.net)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP Specification](https://modelcontextprotocol.io/specification)