🍓 pihole-mcp-serer
About
A Model Context Protocol (MCP) server for Pi-hole
Explore
- 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
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
🍓 pihole-mcp-sererCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
- 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.
Create a .env file in the project root with your Pi-hole credentials:
There are several ways to run the Pi-hole MCP server:
docker-compose up -d
The server will be available at http://localhost:8383
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.
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
},
...
]
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"\ud83c\udf53 pihole-mcp-serer": {
"pihole-mcp-server": {
"command": "uv",
"args": [
"run",
"mcp",
"dev",
"main.py"
]
}
}
}
}McpServers
{
"pihole-mcp-server": {
"command": "uv",
"args": [
"run",
"mcp",
"dev",
"main.py"
]
}
}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
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:
```
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
