pihole-mcp

统一的 Pi-hole v6 MCP 服务器。它将三个上游 MCP (aplaceforallmystuff/mcp-pihole, sbarbett/pihole-mcp-server, cwdcwd/mcp-server-pihole) 的实用工具整合到一个 Python 服务器中，并与 chris2ao-unifi-mcp 技术栈（FastMCP + httpx + Pydantic v2）保持一致。

工具 (28)

统计 (8): get_stats, get_top_blocked, get_top_permitted, get_top_clients, get_query_types, get_forward_destinations, get_recent_blocked, get_history

查询 (2): get_query_log (丰富的过滤器：时间范围、域名、客户端、上游、游标), get_query_suggestions

拦截 (3): get_blocking_status, enable_blocking, disable_blocking (带可选定时器)

域名列表 (6): get_whitelist, get_blacklist, add_to_whitelist, add_to_blacklist, remove_from_whitelist, remove_from_blacklist

本地 DNS (5): list_local_dns, add_local_a_record, remove_local_a_record, add_local_cname_record, remove_local_cname_record

维护 (4): update_gravity, flush_cache, flush_logs, get_tail_log

以及 server_info。

请参阅 docs/plans/consolidated-tool-map.md 获取各工具的端点映射。

Related MCP server: Pi-hole MCP Server

认证

Pi-hole v6 使用基于会话的认证。本服务器会自动处理：

1. POST /api/auth 并携带 {"password": "<app-password>"} 会返回一个会话 SID。

2. 所有后续调用均包含 X-FTL-SID: <sid>。

3. 若遇到 401 错误或接近过期，客户端会自动重新认证并重试一次。

4. 关闭时，DELETE /api/auth 会释放会话。

应用密码 (App password) 在 Pi-hole Web 界面中创建：设置 > Web 界面 > “应用密码” > 生成。这与主管理员 Web 密码不同，是 API 客户端所需的正确凭据。

安装

cd /Users/chris2ao/GitProjects/chris2ao-pihole-mcp
uv sync
cp .env.example .env   # fill in PIHOLE_URL and PIHOLE_PASSWORD
uv run pytest

或者通过包装器（用于 Claude Code 的生产环境）：

~/.claude/scripts/pihole-wrapper.sh

在 Claude Code 中注册

在 ~/.claude.json 的 mcpServers 中添加：

"pihole": {
  "command": "/Users/chris2ao/.claude/scripts/pihole-wrapper.sh",
  "args": []
}

该包装器会从 ~/.claude/secrets/secrets.env 加载 PIHOLE_URL 和 PIHOLE_PASSWORD，然后调用 uv run。

开发

• 运行测试: uv run pytest

• 覆盖率: uv run pytest --cov --cov-report=term

• Python: 3.12+

与 chris2ao-unifi-mcp 的关系

采用相同的技术栈（FastMCP, httpx, Pydantic-settings, hatchling, uv）。比 unifi-mcp 更简单，因为 Pi-hole 是单一产品（没有动态产品加载或发现）。如果您要将其扩展以支持多 Pi-hole 或处理缺失功能（adlist/gravity CRUD、组、DHCP、Teleporter），请遵循 unifi-mcp 的“每个功能一个模块”模式。