Metadata-Version: 2.4
Name: mcp-pihole
Version: 0.1.4
Summary: MCP server for Pi-hole v6
Keywords: mcp,pihole,model-context-protocol
Author: Matthew O'Brien
Author-email: Matthew O'Brien <matthew@obrien.dev>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Networking
Requires-Dist: mcp>=1.27.0,<2
Requires-Dist: httpx>=0.28.0
Requires-Python: >=3.14
Project-URL: Repository, https://github.com/obrien-matthew/mcp-pihole
Project-URL: Issues, https://github.com/obrien-matthew/mcp-pihole/issues
Description-Content-Type: text/markdown

# mcp-pihole

MCP server for Pi-hole v6. Manage blocklists, DNS blocking, domain allow/deny lists, and query diagnostics through the Model Context Protocol.

## Prerequisites

- Python 3.14+
- [uv](https://docs.astral.sh/uv/)
- Pi-hole v6+ with the REST API enabled

## Setup

```bash
uv sync
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PIHOLE_URL` | Yes | Base URL of your Pi-hole instance (e.g., `http://192.168.0.160:8080`) |
| `PIHOLE_PASSWORD` | No | Web interface password. Omit or leave empty for passwordless instances. |

### Claude Code

```bash
claude mcp add pihole \
  -e PIHOLE_URL=http://192.168.0.160:8080 \
  -e PIHOLE_PASSWORD=yourpassword \
  -- uvx mcp-pihole
```

Or add to `.claude/settings.json`:

```json
{
  "mcpServers": {
    "pihole": {
      "command": "uvx",
      "args": ["mcp-pihole"],
      "env": {
        "PIHOLE_URL": "http://192.168.0.160:8080",
        "PIHOLE_PASSWORD": "yourpassword"
      }
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop config:

```json
{
  "mcpServers": {
    "pihole": {
      "command": "uvx",
      "args": ["mcp-pihole"],
      "env": {
        "PIHOLE_URL": "http://192.168.0.160:8080",
        "PIHOLE_PASSWORD": "yourpassword"
      }
    }
  }
}
```

## Tools

### Diagnostics

| Tool | Description |
|------|-------------|
| `get_status` | Pi-hole status summary (queries, blocked count, blocking state) |
| `get_top_domains` | Top queried or blocked domains |
| `get_top_clients` | Top DNS clients by query count |
| `get_queries` | Recent DNS query log with cursor-based pagination |
| `get_version` | Pi-hole FTL version information |

### Blocklist Management

| Tool | Description |
|------|-------------|
| `get_lists` | List all configured blocklists |
| `add_list` | Add a blocklist URL |
| `remove_list` | Remove a blocklist by URL |
| `update_list` | Enable/disable a blocklist or update its comment |
| `update_gravity` | Rebuild gravity database (required after blocklist changes) |

### Domain Management

| Tool | Description |
|------|-------------|
| `get_domains` | List allow/deny domains (exact or regex) |
| `add_domain` | Add a domain to allow or deny list |
| `remove_domain` | Remove a domain from allow or deny list |
| `search_domains` | Check if a domain is blocked and by which list |

### DNS Control and DHCP

| Tool | Description |
|------|-------------|
| `get_blocking_status` | Current DNS blocking status and timer |
| `set_blocking` | Enable/disable blocking, optionally with a timer |
| `get_dhcp_leases` | Current DHCP leases |
| `restart_dns` | Restart the DNS resolver |

## Development

```bash
uv sync
uv run pytest tests/ -x -q
uv run ruff check src/ tests/
uv run pyright src/
```
