mcp-pihole 0.2.0

MCP server for Pi-hole v6

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
• Pi-hole v6+ with the REST API enabled

Setup

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

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:

{
  "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:

{
  "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

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