{
  "markdown": "# MCP Pi-hole Server\n\n[![npm version](https://img.shields.io/npm/v/mcp-pihole-server.svg)](https://www.npmjs.com/package/mcp-pihole-server)\n[![CI](https://github.com/aplaceforallmystuff/mcp-pihole/actions/workflows/ci.yml/badge.svg)](https://github.com/aplaceforallmystuff/mcp-pihole/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)\n\n![Architecture](docs/images/architecture-diagram.png)\n\nAn MCP (Model Context Protocol) server that connects AI assistants like Claude to your [Pi-hole](https://pi-hole.net) network-wide ad blocker. Manage DNS blocking, view statistics, control whitelists/blacklists, and more through natural language.\n\n## Why Use This?\n\nIf you're running Pi-hole on your network, this MCP server lets you:\n\n- **Monitor DNS traffic** - View query statistics, top blocked domains, and client activity\n- **Control blocking** - Enable/disable Pi-hole blocking instantly or with a timer\n- **Manage lists** - Add or remove domains from whitelist and blacklist without opening the web UI\n- **View query logs** - See recent DNS queries with detailed information\n- **Maintain your Pi-hole** - Update gravity (blocklists) and flush DNS cache\n\n## Features\n\n| Category | Tools |\n|----------|-------|\n| **Statistics** | Query totals, blocking percentage, top domains, top clients |\n| **Blocking Control** | Enable, disable (with optional timer), check status |\n| **Domain Lists** | Whitelist/blacklist CRUD operations |\n| **Query Log** | Recent DNS queries with client, status, response time |\n| **Maintenance** | Update gravity, flush cache |\n| **Visualizations** | ASCII art dashboards and bar charts with ANSI colors |\n\n## Prerequisites\n\n- Node.js 18+\n- [Pi-hole](https://pi-hole.net) v6 with API enabled\n- Pi-hole app password (generated in Pi-hole settings)\n- Network access to Pi-hole from your machine\n\n## Installation\n\n### Option 1: Install from npm (recommended)\n\n```bash\nnpx mcp-pihole-server\n```\n\nOr install globally:\n\n```bash\nnpm install -g mcp-pihole-server\n```\n\n### Option 2: Clone and Build\n\n```bash\ngit clone https://github.com/aplaceforallmystuff/mcp-pihole.git\ncd mcp-pihole\nnpm install\nnpm run build\n```\n\n## Configuration\n\n### 1. Get Your Pi-hole App Password\n\n1. Open your Pi-hole web interface\n2. Go to Settings > API\n3. Generate a new app password\n4. Copy the password (it's only shown once)\n\n### 2. Configure Your MCP Client\n\n#### For Claude Desktop\n\nAdd to your Claude Desktop config file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"pihole\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-pihole-server\"],\n      \"env\": {\n        \"PIHOLE_URL\": \"http://your-pihole-address:8080\",\n        \"PIHOLE_PASSWORD\": \"your-app-password\"\n      }\n    }\n  }\n}\n```\n\n#### For Claude Code\n\nAdd to `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"pihole\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-pihole-server\"],\n      \"env\": {\n        \"PIHOLE_URL\": \"http://your-pihole-address:8080\",\n        \"PIHOLE_PASSWORD\": \"your-app-password\"\n      }\n    }\n  }\n}\n```\n\n### Environment Variables\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `PIHOLE_URL` | Pi-hole web interface URL | `http://pihole.local:8080` |\n| `PIHOLE_PASSWORD` | Pi-hole app password | Your app password from settings |\n\n## Usage Examples\n\nOnce configured, you can interact with Pi-hole through natural language:\n\n### View Statistics\n> \"Show me Pi-hole stats\"\n\n> \"What are the top blocked domains?\"\n\n> \"Which clients are making the most queries?\"\n\n### Control Blocking\n> \"Is Pi-hole blocking enabled?\"\n\n> \"Disable Pi-hole for 5 minutes\"\n\n> \"Re-enable Pi-hole blocking\"\n\n### Manage Domain Lists\n> \"Add example.com to the whitelist\"\n\n> \"Block ads.trackersite.com\"\n\n> \"Show me all whitelisted domains\"\n\n### View Query Log\n> \"Show me the last 50 DNS queries\"\n\n> \"What domains has my phone been querying?\"\n\n### Visual Dashboards\n> \"Show me Pi-hole stats with visualize: true\"\n\n> \"Get top blocked domains with visualization\"\n\n## Available Tools\n\n### Statistics\n- `pihole_get_stats` - Get comprehensive Pi-hole statistics\n- `pihole_get_top_blocked` - Get top blocked domains\n- `pihole_get_top_permitted` - Get top permitted domains\n- `pihole_get_top_clients` - Get top clients by query count\n- `pihole_get_query_log` - Get recent DNS queries\n\n### Blocking Control\n- `pihole_get_blocking_status` - Check if blocking is enabled\n- `pihole_enable_blocking` - Enable DNS blocking\n- `pihole_disable_blocking` - Disable blocking (optionally with timer)\n\n### Domain Management\n- `pihole_get_whitelist` - List all whitelisted domains\n- `pihole_get_blacklist` - List all blacklisted domains\n- `pihole_add_to_whitelist` - Add domain to whitelist\n- `pihole_add_to_blacklist` - Add domain to blacklist\n- `pihole_remove_from_whitelist` - Remove domain from whitelist\n- `pihole_remove_from_blacklist` - Remove domain from blacklist\n\n### Maintenance\n- `pihole_update_gravity` - Update blocklists (gravity)\n- `pihole_flush_cache` - Flush DNS cache\n\n## ASCII Visualizations\n\nThis server supports colorful ASCII art visualizations rendered directly in your terminal using ANSI escape codes.\n\n### Supported Tools\n\nThe following tools support the optional `visualize: true` parameter:\n\n| Tool | Visualization |\n|------|---------------|\n| `pihole_get_stats` | Full dashboard with summary stats, top clients, blocked domains, and permitted domains |\n| `pihole_get_top_blocked` | Red bar chart of blocked domains |\n| `pihole_get_top_permitted` | Green bar chart of permitted domains |\n| `pihole_get_top_clients` | Blue bar chart of client activity |\n\n### Usage\n\nPass `visualize: true` to any supported tool:\n\n```json\n{\n  \"name\": \"pihole_get_stats\",\n  \"arguments\": {\n    \"visualize\": true\n  }\n}\n```\n\nWhen `visualize` is not set or `false`, tools return JSON data as usual.\n\n### Example Output\n\n```\n╔════════════════════════════════════════════════════════════════════════════╗\n║                         🛡️  PI-HOLE DASHBOARD                          ║\n╠════════════════════════════════════════════════════════════════════════════╣\n║                                                                            ║\n║ 📊 SUMMARY                                                                 ║\n║ ────────────────────────────────────────────────────────────────────────── ║\n║ Total Queries:      73K             Domains Blocked:    2.4M               ║\n║ Blocked:            22K             Active Clients:     28                 ║\n║ Block Rate:         29.7%           Total Clients:      115                ║\n╠════════════════════════════════════════════════════════════════════════════╣\n║ 🔝 TOP CLIENTS                                                             ║\n║ ────────────────────────────────────────────────────────────────────────── ║\n║ 192.168.1.52     ████████████████████████████████████████   28K (38%)      ║\n║ 192.168.1.51     ███████████████████▋                       14K (19%)      ║\n╚════════════════════════════════════════════════════════════════════════════╝\n```\n\n(Colors appear in terminals that support ANSI escape codes)\n\n## Development\n\n```bash\n# Run in development mode (auto-reloads)\nnpm run watch\n\n# Build for production\nnpm run build\n\n# Run the built version\nnode dist/index.js\n```\n\n## Troubleshooting\n\n### \"PIHOLE_URL and PIHOLE_PASSWORD environment variables are required\"\nEnsure both environment variables are set in your MCP config.\n\n### \"Authentication failed\"\nYour app password is invalid or expired. Generate a new one from Pi-hole Settings > API.\n\n### \"API request failed: 401\"\nSession expired. The server will automatically re-authenticate, but if issues persist, check your password.\n\n### Connection refused\nEnsure Pi-hole is running and the URL is correct. Check that you can access the Pi-hole web interface from your machine.\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Links\n\n- [Pi-hole](https://pi-hole.net)\n- [Pi-hole Documentation](https://docs.pi-hole.net)\n- [Model Context Protocol](https://modelcontextprotocol.io)\n- [MCP Specification](https://modelcontextprotocol.io/specification)\n",
  "bytes": 8457,
  "sha": "3b81dbafc0392f361b9ed6dea829e20295c2e929dd27000196fbd5a962a2a9c7",
  "repo_slug": "aplaceforallmystuff/mcp-pihole",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aplaceforallmystuff_mcp_pihole_f645f43d/readme"
}