pihole-dns-mcp
If you are the rightful owner of pihole-dns-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The DNS Manager MCP Server provides tools to manage DNS host entries and blocking status through the Pi-hole API.
DNS Manager MCP Server
This Model Context Protocol (MCP) server provides tools to manage DNS host entries and blocking status through the Pi-hole API.
Features
- Retrieve a list of current DNS host entries
- Add new DNS host entries
- Delete existing DNS host entries
- Get DNS blocking status
- Enable/disable DNS blocking with optional timers
- Session management with automatic renewal
- Secure password handling through environment variables
Requirements
- Python 3.13 or higher
- A Pi-hole instance with API access
Installation
Clone this repository or download the source code:
git clone https://github.com/lagrz/pihole-dns-mcp.git
cd pihole-dns-mcp
Configuration
The server requires two environment variables to connect to your Pi-hole instance:
DNS_API_BASE_URL="http://10.0.11.41"
DNS_API_PASSWORD="your_api_password"
Additional Configuration Options
You can configure logging behavior with these optional environment variables:
DNS_API_LOG_LEVEL: Set log level (DEBUG, INFO, WARNING, ERROR) - default is INFODNS_API_LOG_TO_FILE: Set to "true" to log to~/.mcp-pihole-api.loginstead of stdout
Example:
DNS_API_LOG_LEVEL=DEBUG
DNS_API_LOG_TO_FILE=true
Using with Claude for Desktop
To integrate with Claude for Desktop:
-
Find your Claude for Desktop configuration:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
- macOS:
-
Add the MCP server configuration:
{
"mcpServers": {
"dns-manager": {
"command": "uv",
"args": ["run", "/absolute/path/to/dns_manager_server.py"],
"env": {
"DNS_API_BASE_URL": "http://10.0.11.41",
"DNS_API_PASSWORD": "your_api_password"
}
}
}
}
- Restart Claude for Desktop
Available Tools
The server provides the following tools:
DNS Host Management
get_dns_hosts: Retrieve all DNS host entries from Pi-holeadd_dns_host: Add a new DNS host entry (IP address and hostname)delete_dns_host: Delete an existing DNS host entry
DNS Blocking Management
get_blocking_status: Get current DNS blocking status and any active timersset_blocking_status: Enable or disable DNS blocking with optional timer
Example Usage in Claude
Once connected to Claude, you can use the following prompts:
DNS Host Management
- "Show me all DNS host entries"
- "Add a DNS host entry for IP 192.168.1.100 with hostname server.local"
- "Remove the DNS host entry for 192.168.1.100 server.local"
DNS Blocking
- "What's the current DNS blocking status?"
- "Enable DNS blocking"
- "Disable DNS blocking for 30 minutes"
- "Enable DNS blocking for 1 hour"
Testing
You can test the server using the MCP inspector:
npx @modelcontextprotocol/inspector uv run dns_manager_server.py
Troubleshooting
Configuration Issues
- Verify your environment variables are set correctly
- Check that your Pi-hole is accessible at the configured URL
- Ensure your Pi-hole password is correct
Connection Issues
- Check if Pi-hole is running and accessible
- Verify the API base URL is correct (include http:// and port if needed)
- Check Claude for Desktop logs for detailed error messages
Authentication Issues
- Verify the Pi-hole password is correct
- Check that API access is enabled in Pi-hole settings
- Review the log file (
~/.mcp-pihole-api.log) for authentication errors
Security Notes
- The API password is stored in environment variables to avoid hardcoding credentials
- Session IDs are cached but automatically renewed when expired
- No sensitive information is logged to standard output
- Session cache file (
~/.mcp-pihole-api.json) is created with secure permissions (0600)
File Locations
The server creates the following files in your home directory:
~/.mcp-pihole-api.json: Session cache (secure permissions)~/.mcp-pihole-api.log: Log file (whenDNS_API_LOG_TO_FILE=true)
Development
The project uses:
