Skip to content
MCP server

Pi-hole MCP Server

Manage Pi-hole v6 DNS blocking, domains, clients, DHCP and query logs from an assistant

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, macOS, Windows
Runs
Locally
Version
0.10.0
Listing updated
2 days ago

About Pi-hole MCP Server

Pi-hole MCP Server is an open-source MCP server for cloud and infrastructure. It runs locally on your machine and is started by your AI client.

This Go server covers roughly 95% of the Pi-hole v6 REST API with 82 tools (84 when a second instance is configured), nine prompts and five resources. You can ask whether blocking is on, pause it for ten minutes, trace why a domain is blocked across every list it could be on, add a local DNS record, find unrecognised network devices or check which upstream resolver is slowest.

Safety controls are the focus. Setting PIHOLE_READ_ONLY hides and rejects every tool that can change anything, enforced on each call, and PIHOLE_TOOLSETS limits it to the families you need. With two Pi-holes, it can diff them and reconcile one onto the other using a dry-run plan and a confirm token before writing. A -check flag tests connections and warns about FTL releases with published security advisories.

Releases carry cosign signatures, SPDX SBOMs and SLSA provenance. Install through Homebrew, Scoop, go install, Docker, deb or rpm packages. Configuration is a Pi-hole URL plus an admin or application password, and an application password bypasses TOTP.

Install

Run in a terminal

claude mcp add pihole-mcp --env PIHOLE_URL='<PIHOLE_URL>' --env PIHOLE_PASSWORD='<PIHOLE_PASSWORD>' -- docker run -i --rm -e PIHOLE_URL -e PIHOLE_PASSWORD ghcr.io/hexamatic/pihole-mcp:0.10.0

Add to claude_desktop_config.json

{
  "mcpServers": {
    "pihole-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PIHOLE_URL",
        "-e",
        "PIHOLE_PASSWORD",
        "ghcr.io/hexamatic/pihole-mcp:0.10.0"
      ],
      "env": {
        "PIHOLE_URL": "<PIHOLE_URL>",
        "PIHOLE_PASSWORD": "<PIHOLE_PASSWORD>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "pihole-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PIHOLE_URL",
        "-e",
        "PIHOLE_PASSWORD",
        "ghcr.io/hexamatic/pihole-mcp:0.10.0"
      ],
      "env": {
        "PIHOLE_URL": "<PIHOLE_URL>",
        "PIHOLE_PASSWORD": "<PIHOLE_PASSWORD>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "pihole-mcp": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PIHOLE_URL",
        "-e",
        "PIHOLE_PASSWORD",
        "ghcr.io/hexamatic/pihole-mcp:0.10.0"
      ],
      "env": {
        "PIHOLE_URL": "<PIHOLE_URL>",
        "PIHOLE_PASSWORD": "<PIHOLE_PASSWORD>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "pihole-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PIHOLE_URL",
        "-e",
        "PIHOLE_PASSWORD",
        "ghcr.io/hexamatic/pihole-mcp:0.10.0"
      ],
      "env": {
        "PIHOLE_URL": "<PIHOLE_URL>",
        "PIHOLE_PASSWORD": "<PIHOLE_PASSWORD>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "pihole-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PIHOLE_URL",
        "-e",
        "PIHOLE_PASSWORD",
        "ghcr.io/hexamatic/pihole-mcp:0.10.0"
      ],
      "env": {
        "PIHOLE_URL": "<PIHOLE_URL>",
        "PIHOLE_PASSWORD": "<PIHOLE_PASSWORD>"
      }
    }
  }
}

Configuration

  • PIHOLE_URLBase URL of your Pi-hole web interface. For multiple Pi-holes use PIHOLE_1_URL, PIHOLE_2_URL, ... instead.Required
  • PIHOLE_PASSWORDPi-hole admin password, or an application password (recommended — bypasses TOTP 2FA)Required
  • TZIANA timezone for rendered timestamps, e.g. Australia/Adelaide. Defaults to UTC in the container.
  • PIHOLE_READ_ONLYExpose only inspection tools. Every tool that can change Pi-hole is hidden and rejected if called.
  • PIHOLE_TLS_SKIP_VERIFYSet to true only for a Pi-hole serving a self-signed HTTPS certificate. A trusted certificate is the better fix.
  • PIHOLE_REQUEST_TIMEOUTHTTP request timeout as a Go duration, e.g. 30s or 1m
  • PIHOLE_MAX_RETRIESRetries after a transient Pi-hole API failure; 0 disables retrying
  • PIHOLE_RETRY_MAX_DELAYUpper bound on a single exponential-backoff wait, as a Go duration

Tools this server provides (10)

Taken from the project documentation; the running server may differ.

pihole_dns_get_blocking
Reports whether DNS blocking is on and for how long.
pihole_dns_set_blocking
Turns blocking on or off, including timed pauses.
pihole_search_domains
Searches which lists contain a domain.
pihole_stats_recent_blocked
Shows recently blocked domains.
pihole_local_dns_add
Adds a local DNS record.
pihole_lists_list
Lists blocklists.
pihole_network_devices
Lists network devices Pi-hole has seen.
pihole_instance_diff
Compares two Pi-hole instances.
pihole_teleporter_export
Exports a configuration backup.
pihole_stats_upstreams
Shows upstream resolver statistics.

What it does

82 Pi-hole tools
Covers domains, lists, groups, clients, DHCP, network, query log, config and local DNS.
Read-only mode
Exposes only inspection tools and rejects changes on every call.
Toolset scoping
Limits the server to chosen tool families to keep the surface small.
Multi-instance diff and sync
Compares two Pi-holes and reconciles with a dry-run plan and confirm token.
Backup and restore
Exports and restores configuration through Teleporter.
Setup check
A -check flag verifies each configured instance and flags affected FTL releases.

Good for

  • Pause ad blocking for a few minutes while testing
  • Work out why a site is blocked and which list caused it
  • Review the most blocked domains for false positives
  • Keep two Pi-holes in step
  • Back up configuration before making changes

Pricing

Open source

Free and open source

Pi-hole MCP Server FAQ

What version of Pi-hole does it need?

Pi-hole v6, using its REST API.

Can I stop it from changing anything?

Yes. PIHOLE_READ_ONLY=true hides and rejects all tools that can change Pi-hole.

What credentials does it need?

The Pi-hole URL and an admin password or application password; the latter bypasses TOTP two-factor.

How is it distributed?

Homebrew, Scoop, go install, Docker, deb and rpm packages and release binaries.

Is Pi-hole MCP Server free?

Yes. Pi-hole MCP Server is open source, so you can use and self-host it for free.

How do I add Pi-hole MCP Server to Claude Code?

Run this command in your terminal: claude mcp add pihole-mcp --env PIHOLE_URL='<PIHOLE_URL>' --env PIHOLE_PASSWORD='<PIHOLE_PASSWORD>' -- docker run -i --rm -e PIHOLE_URL -e PIHOLE_PASSWORD ghcr.io/hexamatic/pihole-mcp:0.10.0

What are the best alternatives to Pi-hole MCP Server?

The closest alternatives to Pi-hole MCP Server are REA, Agent Roast, Midplane, Leash and Tinplate Edge AI Safety, Security & EU Compliance.

Alternatives to Pi-hole MCP Server

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Agent Roast

    MCP server

    Offline review that flags agent changes which weaken tests, assertions or CI

    Runs locally
    • Open source
    • 4 Hacker News points
    • Developer tools
  3. Midplane

    MCP server

    Postgres gateway for AI agents with table grants, column masking and approval for writes

    Runs locally
    • Open source
    • 5 GitHub stars
    • Databases
  4. Leash

    MCP server

    Review what your AI touched, approve risky actions and undo supported changes

    • 1 tool
    • Remote
    • Free
    • 1 GitHub star
    • Security
  5. SecureCloud

    MCP server

    SentinelOne and IT security catalog, prices, quotes and checkout links for Israel

    • 7 tools
    • Remote
    • Free
    • Security