pihole-mcp

A production-grade MCP server for Pi-hole v6.

74 tools | 9 prompts | 5 resources | Single Go binary | ~6MB compressed (slim: ~3.5MB)

Gives AI assistants full control over your Pi-hole instance — DNS blocking, domain management, query analysis, statistics, network devices, DHCP, and system administration. Compatible with the Pi-hole v6 REST API.

Quick Start

Most MCP clients use the same configuration format. Add this to your client's config:

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

Then install the binary via one of the methods below.

Installation

Go Install

go install github.com/hexamatic/pihole-mcp/cmd/pihole-mcp@latest

Docker

docker pull ghcr.io/hexamatic/pihole-mcp:latest

Binary Download

Pre-built binaries for Linux, macOS, and Windows (amd64 and arm64) are available on the Releases page.

Configuration

Application passwords are recommended for automation — they bypass TOTP 2FA and can be revoked independently.

PIHOLE_RATE_LIMIT and PIHOLE_ALLOWED_ORIGINS only apply to the http and sse transports; stdio is a single-process, single-user channel by definition and isn't gated.

Client Setup

The Quick Start config above works for most clients. Expand the section below for client-specific instructions.

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

claude mcp add pihole \
  -e PIHOLE_URL=http://192.168.1.2 \
  -e PIHOLE_PASSWORD=your-password \
  -- pihole-mcp

claude mcp list

{
  "servers": {
    "pihole": {
      "type": "stdio",
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "pihole-mcp",
      "env": {
        "PIHOLE_URL": "http://192.168.1.2",
        "PIHOLE_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "pihole": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PIHOLE_URL=http://192.168.1.2",
        "-e", "PIHOLE_PASSWORD=your-password",
        "ghcr.io/hexamatic/pihole-mcp:latest"]
    }
  }
}

Tools

DNS Control

Statistics

Domain Management

Groups, Clients, Lists

Query Log

System

Actions and Network

Response Options

Most tools accept optional parameters for controlling output:

• detail (minimal | normal | full) — Controls response depth. Default: normal. Use minimal for one-line summaries, full for complete API data.
• format (text | csv) — Output format for tabular data. Default: text. CSV saves ~29% tokens. Available on pihole_domains_list, pihole_lists_list, pihole_clients_list, pihole_queries_search, pihole_network_devices, pihole_stats_top_domains, pihole_stats_top_clients, pihole_stats_upstreams, pihole_stats_query_types, pihole_stats_recent_blocked, pihole_stats_database_top_domains, pihole_stats_database_top_clients, pihole_stats_database_upstreams, pihole_dhcp_leases, and pihole_config_properties.

Prompts

Pre-built multi-step workflows for common tasks:

Advanced Configuration

Transport

By default, pihole-mcp uses stdio (standard for MCP). HTTP and SSE transports are also available:

# Default stdio (for Claude Desktop, Cursor, etc.)
pihole-mcp

# HTTP transport (for web-based MCP clients)
pihole-mcp -transport http -address localhost:8080

# SSE transport
pihole-mcp -transport sse -address localhost:8080

Security (HTTP and SSE transports)

The http and sse transports apply two security middlewares to every request, in line with the MCP 2025-11-25 spec's DNS-rebinding protection guidance. stdio is unaffected (single-process, single-user).

• Origin and Host validation. Both headers must resolve to a host in PIHOLE_ALLOWED_ORIGINS (default loopback only). Missing Origin is allowed for non-browser MCP clients. Mismatches return HTTP 403. To expose pihole-mcp on a LAN, extend the allowlist:

  export PIHOLE_ALLOWED_ORIGINS="localhost,127.0.0.1,[::1],pihole-mcp.lan"
  

  The literal * disables enforcement entirely — only use it if you're behind a reverse proxy doing its own access control.

• Per-session rate limiting. A token bucket keyed by Mcp-Session-Id (fallback to client IP) caps requests at PIHOLE_RATE_LIMIT per minute (default 120, burst max(120/4, 30)). Throttled requests return HTTP 429 with Retry-After: 1. 0 disables.

  # Tighter limit for a small fleet
  export PIHOLE_RATE_LIMIT=60
  
  # Disable (only when running behind a proxy with its own rate limit)
  export PIHOLE_RATE_LIMIT=0
  

OpenTelemetry

Tracing is opt-in. Set OTEL_EXPORTER_OTLP_ENDPOINT to enable:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
pihole-mcp

All tool calls are automatically traced with tool name, duration, and error status.

If you don't need tracing, you can build a slim binary that strips the OpenTelemetry SDK, gRPC, protobuf, and grpc-gateway dependencies entirely (~45% smaller — from 17 MB to 9 MB stripped, 6 MB to 3.5 MB compressed):

just build-slim
# or
go build -tags slim -o bin/pihole-mcp-slim ./cmd/pihole-mcp

The slim binary is functionally identical apart from OTEL_EXPORTER_OTLP_ENDPOINT being ignored.

Development

# Prerequisites: Go 1.26+, Docker, mise, just

# One-command setup
just setup

# Start local Pi-hole (http://localhost:8081, password: test)
just dev-up

# Run quality checks (format + lint + test)
just check

# Run integration tests against local Pi-hole
just integration

# Build binary
just build

See CONTRIBUTING.md for full development guidelines.

Pi-hole is a registered trademark of Pi-hole LLC. This project is independently maintained and is not affiliated with, endorsed by, or sponsored by Pi-hole LLC.

Licence

MIT