pihole-mcp

一个 MCP（模型上下文协议） 服务器，让 Claude 等 AI 助手能够完全控制你的 Pi-hole v6 DNS 广告拦截器——查询日志、允许/拒绝列表、组管理、gravity 重载和统计信息。从第一天起就为多实例部署而设计：通过单个 MCP 端点管理一个或多个 Pi-hole 实例。

为什么？

Pi-hole 的管理 API 功能强大，但用脚本调用起来很繁琐。这个 MCP 服务器将每个 Pi-hole API 操作转化为任何兼容 MCP 的 AI 助手都可以直接调用的工具。无需在管理界面中点击或编写 curl 命令，只需让 AI 检查正在拦截什么、将域名加入白名单，或比较各实例之间的统计信息。

非常适合运行多个 Pi-hole 的家庭实验室用户（主 + 备，或按 VLAN 划分）、大规模管理 DNS 过滤的网络管理员，以及任何希望获得 AI 辅助 DNS 管理的人。

Related MCP server: MCP Pi-hole Server

功能特性

• 多实例支持 - 通过环境变量配置 1 到 N 个 Pi-hole 实例

• 完整的 Pi-hole v6 API 覆盖 - 查询日志、允许/拒绝列表（完整 CRUD）、组管理、拦截控制、本地 DNS（A + CNAME）记录、gravity 重载、统计信息

• 智能正则检测 - 根据元字符分析自动将域名路由到精确或正则列表

• 正则地雷检测器 - 发现看起来应该是正则的拒绝精确条目（分类错误的规则）

• Docker 就绪 - 多阶段 Dockerfile，包含非 root 用户、健康检查和安全性加固

• 可流式 HTTP 传输 - 适用于任何支持基于 HTTP 的 MCP 客户端

• Docker secrets 支持 - 通过环境变量或 /run/secrets/ 文件提供密码

快速开始

Docker（推荐）

git clone https://github.com/ranklancer/pihole-mcp.git
cd pihole-mcp
cp .env.example .env
# Edit .env with your Pi-hole URL(s) and password(s)

mkdir -p secrets
echo "your-pihole-password" > secrets/pihole_password
chmod 600 secrets/pihole_password

cp docker-compose.example.yml docker-compose.yml
docker compose up -d

Node.js

npm install
npm run build
export PIHOLE_INSTANCES=pihole
export PIHOLE_BASE_URL=http://pihole.example.com
export PIHOLE_PASSWORD=your-password
npm start

配置

所有配置均通过环境变量完成。完整参考请参见 .env.example。

单实例

PIHOLE_INSTANCES=pihole
PIHOLE_BASE_URL=http://192.0.2.100
PIHOLE_PASSWORD=your-password

多实例

PIHOLE_INSTANCES=primary,secondary
PRIMARY_BASE_URL=http://192.0.2.100
PRIMARY_PASSWORD=password1
SECONDARY_BASE_URL=https://198.51.100.101
SECONDARY_PASSWORD=password2
SECONDARY_INSECURE_TLS=true

对于 PIHOLE_INSTANCES 中的每个实例名称，请提供：

支持 Docker secrets 作为后备方案：/run/secrets/<name>_password（小写）。

可用的 MCP 工具

每个工具都接受可选的 instance 参数来指定目标 Pi-hole。默认为第一个配置的实例。

连接到你的 MCP 客户端

服务器监听在 http://HOST:PORT/mcp（默认：http://localhost:3000/mcp）。

Claude Desktop / Claude Code

添加到你的 MCP 设置中：

{
  "mcpServers": {
    "pihole": {
      "url": "http://localhost:3031/mcp"
    }
  }
}

Supergateway（stdio 包装器）

如果你的 MCP 客户端仅支持 stdio 传输，请使用 supergateway：

npx -y supergateway --streamableHttp http://localhost:3031/mcp

健康检查

curl http://localhost:3031/health
# {"ok":true,"service":"pihole-mcp","version":"0.3.0"}

开发

npm install
npm run dev     # Watch mode — recompiles on save
npm start       # Run the server

要求

• Node.js >= 20

• 启用了 API 访问的 Pi-hole v6

• 与你的 Pi-hole 实例之间的网络连通性

相关项目

• Pi-hole — 全网广告拦截

• Model Context Protocol — AI 工具集成的开放标准

• MCP Server Registry — MCP 服务器目录

许可证

MIT