{
  "markdown": "# pihole-mcp\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)\n[![Pi-hole v6](https://img.shields.io/badge/Pi--hole-v6-red.svg)](https://pi-hole.net)\n[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple.svg)](https://modelcontextprotocol.io)\n\nAn [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that gives AI assistants like **Claude** full control over your [Pi-hole v6](https://pi-hole.net) DNS ad-blocker - query logs, allow/deny lists, group management, gravity reload, and stats. Designed from day one for **multi-instance deployments**: manage one or many Pi-hole instances from a single MCP endpoint.\n\n## Why?\n\nPi-hole's admin API is powerful but cumbersome to script against. This MCP server turns every Pi-hole API action into a tool that any MCP-compatible AI assistant can call directly. Instead of clicking through the admin UI or writing curl commands, just ask your AI to check what's being blocked, allowlist a domain, or compare stats across instances.\n\nPerfect for **homelabbers** running multiple Pi-holes (primary + secondary, or per-VLAN), **network admins** managing DNS filtering at scale, and anyone who wants AI-assisted DNS management.\n\n## Features\n\n- **Multi-instance support** - configure 1 to N Pi-hole instances via environment variables\n- **Full Pi-hole v6 API coverage** - query logs, allow/deny lists (full CRUD), group management, blocking control, local DNS (A + CNAME) records, gravity reload, stats\n- **Smart regex detection** - automatically routes domains to exact or regex lists based on metacharacter analysis\n- **Regex landmine detector** - finds deny-exact entries that look like they should be regex (miscategorized rules)\n- **Docker-ready** - multi-stage Dockerfile with non-root user, health checks, and security hardening\n- **Streamable HTTP transport** - works with any MCP client that supports HTTP-based MCP\n- **Docker secrets support** - passwords via env vars or `/run/secrets/` files\n\n## Quick Start\n\n### Docker (recommended)\n\n```bash\ngit clone https://github.com/ranklancer/pihole-mcp.git\ncd pihole-mcp\ncp .env.example .env\n# Edit .env with your Pi-hole URL(s) and password(s)\n\nmkdir -p secrets\necho \"your-pihole-password\" > secrets/pihole_password\nchmod 600 secrets/pihole_password\n\ncp docker-compose.example.yml docker-compose.yml\ndocker compose up -d\n```\n\n### Node.js\n\n```bash\nnpm install\nnpm run build\nexport PIHOLE_INSTANCES=pihole\nexport PIHOLE_BASE_URL=http://pihole.example.com\nexport PIHOLE_PASSWORD=your-password\nnpm start\n```\n\n## Configuration\n\nAll configuration is via environment variables. See [`.env.example`](.env.example) for the full reference.\n\n### Single Instance\n\n```env\nPIHOLE_INSTANCES=pihole\nPIHOLE_BASE_URL=http://192.0.2.100\nPIHOLE_PASSWORD=your-password\n```\n\n### Multiple Instances\n\n```env\nPIHOLE_INSTANCES=primary,secondary\nPRIMARY_BASE_URL=http://192.0.2.100\nPRIMARY_PASSWORD=password1\nSECONDARY_BASE_URL=https://198.51.100.101\nSECONDARY_PASSWORD=password2\nSECONDARY_INSECURE_TLS=true\n```\n\nFor each instance name in `PIHOLE_INSTANCES`, provide:\n\n| Variable | Required | Description |\n|---|---|---|\n| `<NAME>_BASE_URL` | Yes | Pi-hole base URL (e.g. `http://pihole.local`) |\n| `<NAME>_PASSWORD` | Yes | Pi-hole API password (or use Docker secrets) |\n| `<NAME>_INSECURE_TLS` | No | Set `true` for self-signed certs (default: `false`) |\n\nDocker secrets are supported as a fallback: `/run/secrets/<name>_password` (lowercase).\n\n## Available MCP Tools\n\n| Tool | Description |\n|---|---|\n| `pihole_query_log` | Fetch query log with filters (limit, time range, client, domain, status) |\n| `pihole_allow_domain` | Add to allowlist (auto-detects exact vs regex) |\n| `pihole_deny_domain` | Add to denylist (auto-detects exact vs regex) |\n| `pihole_list_allowlist` | List all allowlist entries (exact + regex merged) |\n| `pihole_list_denylist` | List all denylist entries (exact + regex merged) |\n| `pihole_stats_summary` | Get Pi-hole statistics summary |\n| `pihole_reload_lists` | Trigger gravity reload |\n| `pihole_group_management` | CRUD operations on Pi-hole groups |\n| `pihole_check_regex_types` | Detect miscategorized regex in deny-exact list |\n| `pihole_set_blocking` | Enable/disable blocking, with optional auto-revert timer |\n| `pihole_domain_management` | Update or delete an allow/deny domain (completes CRUD) |\n| `pihole_local_dns` | List/add/delete local DNS A records |\n| `pihole_local_cname` | List/add/delete local CNAME records |\n\nEvery tool accepts an optional `instance` parameter to target a specific Pi-hole. Defaults to the first configured instance.\n\n## Connecting to Your MCP Client\n\nThe server listens on `http://HOST:PORT/mcp` (default: `http://localhost:3000/mcp`).\n\n### Claude Desktop / Claude Code\n\nAdd to your MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"pihole\": {\n      \"url\": \"http://localhost:3031/mcp\"\n    }\n  }\n}\n```\n\n### Supergateway (stdio wrapper)\n\nIf your MCP client only supports stdio transport, use [supergateway](https://github.com/supercorp-ai/supergateway):\n\n```bash\nnpx -y supergateway --streamableHttp http://localhost:3031/mcp\n```\n\n## Health Check\n\n```bash\ncurl http://localhost:3031/health\n# {\"ok\":true,\"service\":\"pihole-mcp\",\"version\":\"0.3.0\"}\n```\n\n## Development\n\n```bash\nnpm install\nnpm run dev     # Watch mode — recompiles on save\nnpm start       # Run the server\n```\n\n## Requirements\n\n- Node.js >= 20\n- Pi-hole v6 with API access enabled\n- Network connectivity to your Pi-hole instance(s)\n\n## Related Projects\n\n- [Pi-hole](https://pi-hole.net) — Network-wide ad blocking\n- [Model Context Protocol](https://modelcontextprotocol.io) — Open standard for AI tool integration\n- [MCP Server Registry](https://github.com/modelcontextprotocol/servers) — Directory of MCP servers\n\n## License\n\nMIT\n",
  "bytes": 5888,
  "sha": "486e3cd2b0affbe1d1c552660185d514c2f4ca2c8b3b8b2816ef079505b1d05a",
  "repo_slug": "ranklancer/pihole-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ranklancer_pihole_mcp_fab6839c/readme"
}