
Mcp Pihole
io.github.aplaceforallmystuffPublished by GitHub account aplaceforallmystuffv1.0.1Updated Oct 24, 2026
Pi-hole v6 MCP server - manage DNS blocking, stats, whitelists/blacklists
Overview
Connects an assistant to a self-hosted Pi-hole v6 ad blocker to check DNS statistics, toggle blocking, and manage whitelist and blacklist domains.
- What you can do
- Read DNS statistics: query totals, block rate, top blocked and permitted domains, top clients, and recent query logs.
- Turn DNS blocking on or off, optionally with a timer, and check current blocking status.
- List, add and remove domains on the whitelist and blacklist.
- Run maintenance: update gravity blocklists and flush the DNS cache.
- Optionally render statistics as ASCII dashboards and bar charts in the terminal.
- When to use it
- Useful when you run Pi-hole v6 on your network and want to ask about DNS traffic, temporarily lift blocking, or edit allow and block lists in natural language instead of opening the web interface.
- Requirements
- Runs locally via npx or a global npm install, needing Node.js 18 or newer. Requires a reachable Pi-hole v6 instance with the API enabled, the PIHOLE_URL environment variable, and a Pi-hole app password in PIHOLE_PASSWORD. Network access from your machine to Pi-hole is needed.
Installation
In SourceWeft
- Open Mcp Pihole in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
MCP Pi-hole Server
[npm version] [CI] [License: MIT] [MCP]
An MCP (Model Context Protocol) server that connects AI assistants like Claude to your Pi-hole network-wide ad blocker. Manage DNS blocking, view statistics, control whitelists/blacklists, and more through natural language.
Why Use This?
If you're running Pi-hole on your network, this MCP server lets you:
- Monitor DNS traffic - View query statistics, top blocked domains, and client activity
- Control blocking - Enable/disable Pi-hole blocking instantly or with a timer
- Manage lists - Add or remove domains from whitelist and blacklist without opening the web UI
- View query logs - See recent DNS queries with detailed information
- Maintain your Pi-hole - Update gravity (blocklists) and flush DNS cache
Features
Prerequisites
- Node.js 18+
- Pi-hole v6 with API enabled
- Pi-hole app password (generated in Pi-hole settings)
- Network access to Pi-hole from your machine
Installation
Option 1: Install from npm (recommended)
Or install globally:
Option 2: Clone and Build
Configuration
1. Get Your Pi-hole App Password
- Open your Pi-hole web interface
- Go to Settings > API
- Generate a new app password
- Copy the password (it's only shown once)
2. Configure Your MCP Client
For Claude Desktop
Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
For Claude Code
Add to ~/.claude.json:
Environment Variables
Usage Examples
Once configured, you can interact with Pi-hole through natural language:
View Statistics
"Show me Pi-hole stats"
"What are the top blocked domains?"
"Which clients are making the most queries?"
Control Blocking
"Is Pi-hole blocking enabled?"
"Disable Pi-hole for 5 minutes"
"Re-enable Pi-hole blocking"
Manage Domain Lists
"Add example.com to the whitelist"
"Block ads.trackersite.com"
"Show me all whitelisted domains"
View Query Log
"Show me the last 50 DNS queries"
"What domains has my phone been querying?"
Visual Dashboards
"Show me Pi-hole stats with visualize: true"
"Get top blocked domains with visualization"
Available Tools
Statistics
pihole_get_stats- Get comprehensive Pi-hole statisticspihole_get_top_blocked- Get top blocked domainspihole_get_top_permitted- Get top permitted domainspihole_get_top_clients- Get top clients by query countpihole_get_query_log- Get recent DNS queries
Blocking Control
pihole_get_blocking_status- Check if blocking is enabledpihole_enable_blocking- Enable DNS blockingpihole_disable_blocking- Disable blocking (optionally with timer)
Domain Management
pihole_get_whitelist- List all whitelisted domainspihole_get_blacklist- List all blacklisted domainspihole_add_to_whitelist- Add domain to whitelistpihole_add_to_blacklist- Add domain to blacklistpihole_remove_from_whitelist- Remove domain from whitelistpihole_remove_from_blacklist- Remove domain from blacklist
Maintenance
pihole_update_gravity- Update blocklists (gravity)pihole_flush_cache- Flush DNS cache
ASCII Visualizations
This server supports colorful ASCII art visualizations rendered directly in your terminal using ANSI escape codes.
Supported Tools
The following tools support the optional visualize: true parameter:
Usage
Pass visualize: true to any supported tool:
When visualize is not set or false, tools return JSON data as usual.
Example Output
(Colors appear in terminals that support ANSI escape codes)
Development
Troubleshooting
"PIHOLE_URL and PIHOLE_PASSWORD environment variables are required"
Ensure both environment variables are set in your MCP config.
"Authentication failed"
Your app password is invalid or expired. Generate a new one from Pi-hole Settings > API.
"API request failed: 401"
Session expired. The server will automatically re-authenticate, but if issues persist, check your password.
Connection refused
Ensure Pi-hole is running and the URL is correct. Check that you can access the Pi-hole web interface from your machine.
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
License
MIT License - see LICENSE for details.
Links
Source: README.md at commit ac5c0d7
Tools
0Version history
1- v1.0.1LatestSep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts