pihole-mcp-server

# 🍓 pihole-mcp-serer A Model Context Protocol (MCP) server for Pi-hole. This server exposes Pi-hole functionality as tools that can be used by AI assistants. ## Dependencies ### Docker - [Docker install guide](https://docs.docker.com/engine/install/) ### `uv` (Optional, for Development) If you want to run the application locally, use `uv`. Install it with your package manager of choice. ## Environment Create a `.env` file in the project root with your Pi-hole credentials: ``` # Primary Pi-hole (required) PIHOLE_URL=https://your-pihole.local/ PIHOLE_PASSWORD=your-admin-password #PIHOLE_NAME=Primary # optional, defaults to URL if unset # Secondary Pi-hole (optional) #PIHOLE2_URL=https://secondary-pihole.local/ #PIHOLE2_PASSWORD=password2 #PIHOLE2_NAME=Secondary # optional # Up to 4 Pi-holes: #PIHOLE3_URL=... #PIHOLE3_PASSWORD=... #PIHOLE3_NAME=... #PIHOLE4_URL=... #PIHOLE4_PASSWORD=... #PIHOLE4_NAME=... ``` ## Project Structure The project follows a modular organization for better maintainability: ``` / ├── main.py # Main application entry point ├── tools/ # Pi-hole tools organized by functionality │ ├── __init__.py │ ├── config.py # Configuration-related tools (DNS settings) │ └── metrics.py # Metrics and query-related tools ├── resources/ # MCP resources │ ├── __init__.py │ └── common.py # Common resources (piholes://, version://) ├── docker-compose.yml # Docker Compose configuration for production ├── docker-compose.dev.yml # Docker Compose for development with volume mounts └── Dockerfile # Docker build configuration ``` This structure separates the code into logical components while maintaining compatibility with all run modes. ## Running the Server There are several ways to run the Pi-hole MCP server: ### Using Docker (Recommended for Production) ```bash # Standard deployment docker-compose up -d ``` The server will be available at `http://localhost:8383` ### Development Mode with Docker For development, use the dev compose file which builds locally: ```bash docker-compose -f docker-compose.dev.yml up ``` ### MCP Inspector You can run the MCP inspector using `uv` and the `mcp` CLI: ```bash uv run mcp dev main.py ``` This will start an interactive interface at `http://localhost:6274` where you can test tools and resources. ## API This MCP server exposes the following resources and tools: ### Resources - `piholes://`: Returns information about all configured Pi-holes - `version://`: Returns the MCP server version - `list-tools://`: Returns a list of tool categories - `list-tools://{category}`: Returns a list of tools within a specific category ### Tools Each tool call returns results as a list of dictionaries with the following structure: ``` [ { "pihole": "Pi-hole Name", "data": [...] # Result data from this Pi-hole }, ... ] ``` #### Configuration - `list_local_dns`: Lists all local DNS settings from Pi-hole(s) - `add_local_a_record`: Adds a local A record to Pi-hole(s). - `add_local_cname_record`: Adds a local CNAME record to Pi-hole(s). - `remove_local_a_record`: Removes all A records for a hostname. - `remove_local_cname_record`: Removes all CNAME records for a hostname. #### Metrics - `list_queries`: Fetches the recent DNS query history from Pi-hole(s) - `list_query_suggestions`: Get query filter suggestions - `list_query_history`: Get activity graph data for queries over time ## Testing in `goose` Goose is a CLI LLM client that's useful for testing and development. Follow their install instructions [here](https://block.github.io/goose/docs/quickstart/). The following assumes you've completed the initial setup with `goose configure`. ### Configure Extension 1. Type `goose configure` to open the configuration menu. 2. Select **Add Extension** 3. Select **Remote Extension** 4. It will ask for a name. It doesn't matter what you name it. I called mine `pihole-mcp`. 5. When it asks _"What is the SSE endpoint URI?"_ enter `http://localhost:8383/sse`. 6. Enter a timeout. 7. Add a description if you'd like. 8. Select **No** when it asks about environment variables.  ### Start a Session Once the server is installed, start a chat session. ```sh goose session ``` Try asking it: _"What are my local DNS records?"_  ...or telling it: _"Show me my recent DNS queries."_  ## Claude Desktop Claude's desktop client currently only support's the STDIO protocol, however you can use a proxy to communicate with the SSE endpoint. Add the following to your `claude_desktop_config.json` file. ```json { "mcpServers": { "pihole": { "command": "npx", "args": [ "mcp-remote", "http://localhost:8383/sse" ] } } } ``` If you're connecting to a different host on your local network and using an unsecured connection, you'll need to explicitly allow it with the `--allow-http` argument. For example: ```json { "mcpServers": { "pihole": { "command": "npx", "args": [ "mcp-remote", "http://192.168.1.255:8383/sse", "--allow-http" ] } } } ``` Afterwards, completely restart the application and try it out.   ## License [MIT](./LICENSE)