Pi-hole

You set up an MCP server that exposes Pi-hole functionality as reusable tools for AI assistants. It lets you query Pi-hole data, manage local DNS records, and inspect DNS activity across one or more Pi-hole instances from a unified interface.

How to use

You interact with the Pi-hole MCP server through an MCP client or the built-in inspector. Start the server, then connect your client to the server’s root URL to browse resources and run tools. Key capabilities include listing Pi-holes, querying and filtering DNS data, and creating or removing local DNS records across configured Pi-holes.

To test and run basic actions, use the inspector interface to explore tools and resources. You can fetch recent DNS queries, list available tools by category, and verify that your Pi-hole credentials are working by querying local DNS settings.

How to install

Prerequisites: you need Docker installed on your machine. If you are developing or testing locally, you can also use the development setup with a dedicated compose file and local builds. The Python-based server is started via standard commands described below.

Step 1: Prepare environment variables for Pi-hole access. Create a file named .env in the project root and populate the credentials for your Pi-hole instances.

Step 2: Run the production server with Docker Compose.

Step 3: (Optional) Run a development setup that builds locally.

Running the server

Production deployment using Docker Compose is the recommended approach. After you have your environment configured, start the services in detached mode.

# Standard deployment
docker-compose up -d

Development and inspection

If you want to develop locally or test interactively, you can use the development compose file and the MCP Inspector to explore tools and resources.

docker-compose -f docker-compose.dev.yml up

To test the MCP server directly through an interactive inspector, run the following to launch the inspector UI on your machine.

uv run mcp dev main.py

Claude Desktop integration

Claude Desktop can connect via the STDIO protocol through a local SSE endpoint. Create a configuration that runs the remote MCP client pointing at the local SSE URL.

{
  "mcpServers": {
    "pihole": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8383/sse"
      ]
    }
  }
}

Testing in goose

Goose is a CLI LLM client you can use to test the MCP server during development. After configuring Goose, start a session and try queries like asking for local DNS records or recent DNS traffic.

goose session

Notes and security

Store Pi-hole credentials securely in the environment file and restrict access to the server. When exposing the MCP server over a network, prefer secure connections and proper authentication for any remote clients.

What you can do with the MCP server

This MCP server exposes a set of resources and tools to manage Pi-hole configurations and monitor DNS activity.

Available tools

list_local_dns

List all local DNS settings from Pi-hole(s) so you can review current names and configurations.

add_local_a_record

Add a local A record to Pi-hole(s) to map a hostname to an IP address.

add_local_cname_record

Add a local CNAME record to Pi-hole(s) to alias one hostname to another.

remove_local_a_record

Remove all A records for a given hostname from Pi-hole(s).

remove_local_cname_record

Remove all CNAME records for a given hostname from Pi-hole(s).

list_queries

Fetch the most recent DNS query history from Pi-hole(s).

list_query_suggestions

Provide query filter suggestions to refine searches.

list_query_history

Return activity graph data showing DNS queries over time.