🍓 pihole-mcp-serer

What is 🍓 pihole-mcp-serer?

The 🍓 pihole-mcp-serer is a Model Context Protocol (MCP) server that exposes Pi-hole functionality as tools for AI assistants. It allows AI tools to manage local DNS records, query DNS history, and retrieve metrics from one or multiple Pi-hole instances.

How to use 🍓 pihole-mcp-serer?

Create a .env file with PIHOLE_URL and PIHOLE_PASSWORD (and optionally up to three additional Pi-holes). Run the server via Docker (docker-compose up -d) for production or with uv run mcp dev main.py for development. Then configure an MCP client (e.g., Goose or Claude Desktop) to connect to the SSE endpoint at http://localhost:8383/sse.

Key features of 🍓 pihole-mcp-serer

• Manage local DNS A and CNAME records
• Query recent DNS query history
• Get query filter suggestions
• Retrieve activity graph data over time
• Support up to four Pi-hole instances
• Deploy with Docker for easy production use

Use cases of 🍓 pihole-mcp-serer

• Ask an AI assistant to list all local DNS records
• Add a new local A record via a chat interface
• Remove a misconfigured CNAME record
• Query recent DNS lookups for troubleshooting
• Monitor Pi-hole activity through a conversational agent

FAQ from 🍓 pihole-mcp-serer

What are the dependencies?

Docker is required for production deployment. For development, uv is optional to run the server locally.

How do I configure multiple Pi-holes?

Add PIHOLE2_URL, PIHOLE2_PASSWORD, and optionally PIHOLE2_NAME in the .env file. Repeat for up to four Pi-holes.

How do I run the server without Docker?

Use uv run mcp dev main.py after installing uv and any required dependencies.

What transport protocol does it use?

The server uses SSE (Server-Sent Events) on port 8383 by default. Clients like Goose connect directly; Claude Desktop uses a proxy (mcp-remote) to bridge STDIO to SSE.

How does authentication work?

Credentials are set via environment variables (PIHOLE_URL, PIHOLE_PASSWORD) in the .env file. No other authentication mechanism is documented.