🍓 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

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)

# 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:

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

MCP Inspector

You can run the MCP inspector using uv and the mcp CLI:

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