Pi-hole MCP Server MCP Server

Name: Pi-hole MCP Server MCP Server
Author: io.github.hexamatic

io.github.hexamatic/pihole-mcp

Repository Registry

What is the Pi-hole MCP Server MCP server?

Manage Pi-hole v6: DNS blocking, domains, clients, query analysis, DHCP, and multi-instance sync.

How to install Pi-hole MCP Server

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

Environment / auth

PIHOLE_URL
required
Base URL of your Pi-hole web interface. For multiple Pi-holes use PIHOLE_1_URL, PIHOLE_2_URL, ... instead.
PIHOLE_PASSWORD
required
secret
Pi-hole admin password, or an application password (recommended — bypasses TOTP 2FA)
TZ
IANA timezone for rendered timestamps, e.g. Australia/Adelaide. Defaults to UTC in the container.
PIHOLE_TLS_SKIP_VERIFY
Set to true only for a Pi-hole serving a self-signed HTTPS certificate. A trusted certificate is the better fix.
PIHOLE_REQUEST_TIMEOUT
HTTP request timeout as a Go duration, e.g. 30s or 1m
PIHOLE_MAX_RETRIES
Retries after a transient Pi-hole API failure; 0 disables retrying
PIHOLE_RETRY_MAX_DELAY
Upper bound on a single exponential-backoff wait, as a Go duration

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pihole-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/hexamatic/pihole-mcp:0.8.0"
      ],
      "env": {
        "PIHOLE_URL": "<YOUR_PIHOLE_URL>",
        "PIHOLE_PASSWORD": "<YOUR_PIHOLE_PASSWORD>",
        "TZ": "<YOUR_TZ>",
        "PIHOLE_TLS_SKIP_VERIFY": "<YOUR_PIHOLE_TLS_SKIP_VERIFY>",
        "PIHOLE_REQUEST_TIMEOUT": "<YOUR_PIHOLE_REQUEST_TIMEOUT>",
        "PIHOLE_MAX_RETRIES": "<YOUR_PIHOLE_MAX_RETRIES>",
        "PIHOLE_RETRY_MAX_DELAY": "<YOUR_PIHOLE_RETRY_MAX_DELAY>"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "pihole-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/hexamatic/pihole-mcp:0.8.0"
      ],
      "env": {
        "PIHOLE_URL": "<YOUR_PIHOLE_URL>",
        "PIHOLE_PASSWORD": "<YOUR_PIHOLE_PASSWORD>",
        "TZ": "<YOUR_TZ>",
        "PIHOLE_TLS_SKIP_VERIFY": "<YOUR_PIHOLE_TLS_SKIP_VERIFY>",
        "PIHOLE_REQUEST_TIMEOUT": "<YOUR_PIHOLE_REQUEST_TIMEOUT>",
        "PIHOLE_MAX_RETRIES": "<YOUR_PIHOLE_MAX_RETRIES>",
        "PIHOLE_RETRY_MAX_DELAY": "<YOUR_PIHOLE_RETRY_MAX_DELAY>"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "pihole-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/hexamatic/pihole-mcp:0.8.0"
      ],
      "env": {
        "PIHOLE_URL": "<YOUR_PIHOLE_URL>",
        "PIHOLE_PASSWORD": "<YOUR_PIHOLE_PASSWORD>",
        "TZ": "<YOUR_TZ>",
        "PIHOLE_TLS_SKIP_VERIFY": "<YOUR_PIHOLE_TLS_SKIP_VERIFY>",
        "PIHOLE_REQUEST_TIMEOUT": "<YOUR_PIHOLE_REQUEST_TIMEOUT>",
        "PIHOLE_MAX_RETRIES": "<YOUR_PIHOLE_MAX_RETRIES>",
        "PIHOLE_RETRY_MAX_DELAY": "<YOUR_PIHOLE_RETRY_MAX_DELAY>"
      }
    }
  }
}

VS Code

.vscode/mcp.json

{
  "servers": {
    "pihole-mcp": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/hexamatic/pihole-mcp:0.8.0"
      ],
      "env": {
        "PIHOLE_URL": "<YOUR_PIHOLE_URL>",
        "PIHOLE_PASSWORD": "<YOUR_PIHOLE_PASSWORD>",
        "TZ": "<YOUR_TZ>",
        "PIHOLE_TLS_SKIP_VERIFY": "<YOUR_PIHOLE_TLS_SKIP_VERIFY>",
        "PIHOLE_REQUEST_TIMEOUT": "<YOUR_PIHOLE_REQUEST_TIMEOUT>",
        "PIHOLE_MAX_RETRIES": "<YOUR_PIHOLE_MAX_RETRIES>",
        "PIHOLE_RETRY_MAX_DELAY": "<YOUR_PIHOLE_RETRY_MAX_DELAY>"
      }
    }
  }
}

Claude Code

claude mcp add pihole-mcp --env PIHOLE_URL=<YOUR_PIHOLE_URL> --env PIHOLE_PASSWORD=<YOUR_PIHOLE_PASSWORD> --env TZ=<YOUR_TZ> --env PIHOLE_TLS_SKIP_VERIFY=<YOUR_PIHOLE_TLS_SKIP_VERIFY> --env PIHOLE_REQUEST_TIMEOUT=<YOUR_PIHOLE_REQUEST_TIMEOUT> --env PIHOLE_MAX_RETRIES=<YOUR_PIHOLE_MAX_RETRIES> --env PIHOLE_RETRY_MAX_DELAY=<YOUR_PIHOLE_RETRY_MAX_DELAY> -- docker run -i --rm ghcr.io/hexamatic/pihole-mcp:0.8.0