pihole

This MCP server exposes Pi-hole functionality as a set of tools that can be invoked by AI assistants through MCP. The server reads Pi-hole credentials from environment variables and provides resources such as piholes:// to fetch Pi-hole information, version:// to report the server version, and list-tools:// to discover available tool categories. Tools are organized by functionality (e.g., DNS configuration and metrics). To use it, deploy via Docker (recommended for production) or run in development with uv. You can then query or call specific tools like list_local_dns, add_local_a_record, list_queries, and list_query_history to manage DNS records and inspect query data across configured Pi-holes. For Claude and other clients, you can point them to the SSE endpoint http://localhost:8383/sse or to your host/port if running remotely, and use the provided tools to manage DNS records and view metrics.

Prerequisites:

• Docker and Docker Compose installed on the host
• Optional: uv for development (Python development workflow)

Installation steps:

1. Clone the MCP server repository git clone https://github.com/your-org/sbarbett-pihole-mcp-server.git cd sbarbett-pihole-mcp-server

2. Prepare environment Create a .env file at the project root with your Pi-hole credentials, for example: PIHOLE_URL=https://your-pihole.local/ PIHOLE_PASSWORD=your-admin-password PIHOLE_NAME=Primary (Other optional Pi-hole definitions can be added as needed)

3. Start the server (production recommended via Docker) docker-compose up -d The server will be available at http://localhost:8383

4. (Optional) Development run with uv uv run main.py This will start the development server and expose an interactive MCP inspector at http://localhost:6274

5. Verify Access the MCP resources, for example: http://localhost:8383/ (or via the SSE endpoint http://localhost:8383/sse for clients like Claude)

Note: If you need to run only a specific subset or customize the environment, adjust the docker-compose.yml or the environment variables in the .env file accordingly.

Tips and common considerations:

• The server supports up to four Pi-hole instances via PIHOLE, PIHOLE2, PIHOLE3, and PIHOLE4 related environment variables.
• Ensure PIHOLE_URL and PIHOLE_PASSWORD are set for at least the primary Pi-hole; other Pi-hole definitions are optional.
• When using Claude or other clients, you may need to add --allow-http if you are using an unsecured local endpoint.
• The MCP inspector (uv) helps test tools and resources locally before production deployment.
• If you edit docker-compose.yml, remember to re-run docker-compose up -d to apply changes.
• The npm_package field is null since this MCP server is Python-based and not distributed as an npm package.