Exposes Pi-hole functionality through tools for listing local DNS settings and retrieving recent DNS query history from a Pi-hole instance.
🍓 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
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:
Project Structure
The project follows a modular organization for better maintainability:
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)
The server will be available at http://localhost:8383
Development Mode with Docker
For development, use the dev compose file which builds locally:
MCP Inspector
You can run the MCP inspector using uv
and the mcp
CLI:
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-holesversion://
: Returns the MCP server versionlist-tools://
: Returns a list of tool categorieslist-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:
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 suggestionslist_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.
The following assumes you've completed the initial setup with goose configure
.
Configure Extension
- Type
goose configure
to open the configuration menu. - Select Add Extension
- Select Remote Extension
- It will ask for a name. It doesn't matter what you name it. I called mine
pihole-mcp
. - When it asks "What is the SSE endpoint URI?" enter
http://localhost:8383/sse
. - Enter a timeout.
- Add a description if you'd like.
- Select No when it asks about environment variables.
Start a Session
Once the server is installed, start a chat 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.
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:
Afterwards, completely restart the application and try it out.
License
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A server that exposes Pi-hole functionality as tools for AI assistants, allowing them to retrieve local DNS settings and query history through natural language.
Related MCP Servers
- AsecurityAlicenseAqualityProvides comprehensive access to Roam Research's API functionality. This server enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface.Last updated -181158TypeScriptMIT License
- -securityAlicense-qualityA server that enables AI assistants like Claude to safely run Python code and access websites, processing data for better AI understanding while providing helpful error messages.Last updated -3PythonGPL 3.0
- -securityAlicense-qualityA simple MCP server that enables AI assistants to perform domain research including availability checking, WHOIS lookups, DNS record retrieval, and finding expired domains without requiring API keys.Last updated -26PythonMIT License
- -securityAlicense-qualityA server that enables AI assistants to access Polarsteps travel data, allowing queries about user profiles, trip details, travel statistics, and natural language search through travel histories.Last updated -2PythonMIT License