# Pi-hole MCP Server

> Pi-hole MCP Server is an open-source MCP server for cloud and infrastructure. Manage Pi-hole v6 DNS blocking, domains, clients, DHCP and query logs from an assistant. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Windows, Linux, self-hosted
- **Repository:** https://github.com/hexamatic/pihole-mcp
- **MCP Registry name:** io.github.hexamatic/pihole-mcp
- **Categories:** cloud and infrastructure, security
- **Listing updated:** 2026-11-15

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
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
```

### Claude Desktop (claude_desktop_config.json)

```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>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```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>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```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>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```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>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```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>"
      }
    }
  }
}
```

## Tools

- `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.

## 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

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Agent Roast](https://ai-powered.com/mcp/agent-roast): Agent Roast is an open-source MCP server for developer tools.
- [Midplane](https://ai-powered.com/mcp/midplane): Midplane is an open-source MCP server for databases.
- [Leash](https://ai-powered.com/mcp/leash): Leash is a free MCP server for security.
- [Tinplate Edge AI Safety, Security & EU Compliance](https://ai-powered.com/mcp/tinplate-edge-ai-safety-security-and-eu-compliance): Tinplate Edge AI Safety, Security & EU Compliance is a freemium MCP server for security.
- [SecureCloud](https://ai-powered.com/mcp/securecloud): SecureCloud is a free MCP server for security.
- [Eikino](https://ai-powered.com/mcp/eikino): Eikino is a freemium MCP server for security.
- [SynomosAI Governance MCP](https://ai-powered.com/mcp/synomosai-governance-mcp-2): SynomosAI Governance MCP is an open-source MCP server for security.

---
Source: https://ai-powered.com/mcp/pi-hole-mcp-server
