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

AI-generated 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.
Before you install
The Pi-hole app password is supplied in plain text through the PIHOLE_PASSWORD environment variable, so keep the client config file protected. Several tools change state on your network: disabling blocking, adding or removing list entries, updating gravity and flushing the cache. Query logs expose client IP addresses and browsing domains.

Installation

In SourceWeft

  1. Open Mcp Pihole in the dashboard and add it to a workspace.
  2. 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]

[Architecture]

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

CategoryTools
StatisticsQuery totals, blocking percentage, top domains, top clients
Blocking ControlEnable, disable (with optional timer), check status
Domain ListsWhitelist/blacklist CRUD operations
Query LogRecent DNS queries with client, status, response time
MaintenanceUpdate gravity, flush cache
VisualizationsASCII art dashboards and bar charts with ANSI colors

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)

bash
npx mcp-pihole-server

Or install globally:

bash
npm install -g mcp-pihole-server

Option 2: Clone and Build

bash
git clone https://github.com/aplaceforallmystuff/mcp-pihole.gitcd mcp-piholenpm installnpm run build

Configuration

1. Get Your Pi-hole App Password

  1. Open your Pi-hole web interface
  2. Go to Settings > API
  3. Generate a new app password
  4. 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

json
{  "mcpServers": {    "pihole": {      "command": "npx",      "args": ["-y", "mcp-pihole-server"],      "env": {        "PIHOLE_URL": "http://your-pihole-address:8080",        "PIHOLE_PASSWORD": "your-app-password"      }    }  }}
For Claude Code

Add to ~/.claude.json:

json
{  "mcpServers": {    "pihole": {      "command": "npx",      "args": ["-y", "mcp-pihole-server"],      "env": {        "PIHOLE_URL": "http://your-pihole-address:8080",        "PIHOLE_PASSWORD": "your-app-password"      }    }  }}

Environment Variables

VariableDescriptionExample
PIHOLE_URLPi-hole web interface URLhttp://pihole.local:8080
PIHOLE_PASSWORDPi-hole app passwordYour app password from settings

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 statistics
  • pihole_get_top_blocked - Get top blocked domains
  • pihole_get_top_permitted - Get top permitted domains
  • pihole_get_top_clients - Get top clients by query count
  • pihole_get_query_log - Get recent DNS queries

Blocking Control

  • pihole_get_blocking_status - Check if blocking is enabled
  • pihole_enable_blocking - Enable DNS blocking
  • pihole_disable_blocking - Disable blocking (optionally with timer)

Domain Management

  • pihole_get_whitelist - List all whitelisted domains
  • pihole_get_blacklist - List all blacklisted domains
  • pihole_add_to_whitelist - Add domain to whitelist
  • pihole_add_to_blacklist - Add domain to blacklist
  • pihole_remove_from_whitelist - Remove domain from whitelist
  • pihole_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:

ToolVisualization
pihole_get_statsFull dashboard with summary stats, top clients, blocked domains, and permitted domains
pihole_get_top_blockedRed bar chart of blocked domains
pihole_get_top_permittedGreen bar chart of permitted domains
pihole_get_top_clientsBlue bar chart of client activity

Usage

Pass visualize: true to any supported tool:

json
{  "name": "pihole_get_stats",  "arguments": {    "visualize": true  }}

When visualize is not set or false, tools return JSON data as usual.

Example Output

╔════════════════════════════════════════════════════════════════════════════╗║                         🛡️  PI-HOLE DASHBOARD                          ║╠════════════════════════════════════════════════════════════════════════════╣║                                                                            ║║ 📊 SUMMARY                                                                 ║║ ────────────────────────────────────────────────────────────────────────── ║║ Total Queries:      73K             Domains Blocked:    2.4M               ║║ Blocked:            22K             Active Clients:     28                 ║║ Block Rate:         29.7%           Total Clients:      115                ║╠════════════════════════════════════════════════════════════════════════════╣║ 🔝 TOP CLIENTS                                                             ║║ ────────────────────────────────────────────────────────────────────────── ║║ 192.168.1.52     ████████████████████████████████████████   28K (38%)      ║║ 192.168.1.51     ███████████████████▋                       14K (19%)      ║╚════════════════════════════════════════════════════════════════════════════╝

(Colors appear in terminals that support ANSI escape codes)

Development

bash
# Run in development mode (auto-reloads)npm run watch
# Build for productionnpm run build
# Run the built versionnode dist/index.js

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

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  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