Pi-hole MCP Server

pihole-mcp

一个 MCP（Model Context Protocol） 服务，可让 Claude 等 AI 助手全面控制你的 Pi-hole v6 DNS 广告拦截器，包括查询日志、允许/拒绝列表、分组管理、Gravity 重新加载和统计信息。本项目从一开始就针对多实例部署设计：通过单个 MCP 端点管理一个或多个 Pi-hole 实例。

为什么使用它？

Pi-hole 的管理 API 功能强大，但不便于编写脚本。本 MCP 服务将每项 Pi-hole API 操作都封装为工具，任何兼容 MCP 的 AI 助手都可以直接调用。无需在管理界面中逐项点击或编写 curl 命令，只需让 AI 检查拦截情况、将域名加入允许列表，或比较多个实例的统计信息。

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

功能特性

• 多实例支持 - 通过环境变量配置 1 到 N 个 Pi-hole 实例
• 全面覆盖 Pi-hole v6 API - 查询日志、允许/拒绝列表（完整 CRUD）、分组和客户端管理、拦截控制、本地 DNS（A + CNAME）记录、Gravity 重新加载、统计信息
• 智能正则表达式检测 - 根据元字符分析，自动将域名路由至精确匹配列表或正则表达式列表
• 正则表达式隐患检测器 - 查找看起来应该使用正则表达式的精确拒绝条目（分类错误的规则）
• 支持 Docker - 多阶段 Dockerfile，包含非 root 用户、健康检查和安全加固
• Streamable HTTP 或 stdio 传输 - 可作为长期运行的 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

本地按需启动（stdio，无需 Docker）

MCP 客户端需要时会将服务作为子进程启动，并通过 stdin/stdout 与其通信。不会开放端口，也不会有程序在后台持续运行。

npm ci
npm run build
cp .env.example .env
chmod 600 .env
# Edit .env with your Pi-hole URL(s) and password(s)

将其注册到 Claude Code（用户范围）：

claude mcp add --scope user pihole -- bash -c \
  'set -a; . ~/path/to/pihole-mcp/.env; set +a; MCP_TRANSPORT=stdio exec node ~/path/to/pihole-mcp/dist/index.js'

或者手动添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "pihole": {
      "type": "stdio",
      "command": "bash",
      "args": ["-c", "set -a; . ~/path/to/pihole-mcp/.env; set +a; MCP_TRANSPORT=stdio exec node ~/path/to/pihole-mcp/dist/index.js"]
    }
  }
}

stdio 模式下会忽略 .env 中的 HOST 和 PORT。

配置

所有配置均通过环境变量完成。完整参考请参见 .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 中的每个实例名称，请提供：

变量	必填	描述
<NAME>_BASE_URL	是	Pi-hole 基础 URL（例如 http://pihole.local）
<NAME>_PASSWORD	是	Pi-hole API 密码（也可使用 Docker secrets）
<NAME>_INSECURE_TLS	否	自签名证书设为 true（默认：false）

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

可用的 MCP 工具

工具	描述
pihole_query_log	获取带筛选条件的查询日志（数量上限、时间范围、客户端 IP 或名称、域名、状态）
pihole_allow_domain	添加到允许列表（自动检测精确匹配或正则表达式）
pihole_deny_domain	添加到拒绝列表（自动检测精确匹配或正则表达式）
pihole_list_allowlist	列出所有允许列表条目（合并精确匹配和正则表达式）
pihole_list_denylist	列出所有拒绝列表条目（合并精确匹配和正则表达式）
pihole_stats_summary	获取 Pi-hole 统计摘要
pihole_reload_lists	触发 gravity 重新加载
pihole_group_management	对 Pi-hole 分组执行 CRUD 操作
pihole_client_management	对 Pi-hole 客户端及其分组分配执行 CRUD 操作
pihole_check_regex_types	检测拒绝列表精确匹配项中分类错误的正则表达式
pihole_set_blocking	启用/禁用拦截，可选自动恢复计时器
pihole_domain_management	更新或删除允许/拒绝域名（补全 CRUD）
pihole_local_dns	列出/添加/删除本地 DNS A 记录
pihole_local_cname	列出/添加/删除本地 CNAME 记录

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

连接到 MCP 客户端

本节适用于 HTTP 传输（Docker 或 npm start）。关于 stdio，请参阅按需本地运行。

服务监听 http://HOST:PORT/mcp（默认：http://localhost:3000/mcp）。HTTP 端点没有身份验证，因此请确保它仅绑定到 localhost 或受信任的网络。

Claude Desktop / Claude Code

将以下内容添加到 MCP 设置中：

{
  "mcpServers": {
    "pihole": {
      "url": "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
• Pi-hole v6，并已启用 API 访问
• 可连接到 Pi-hole 实例的网络

相关项目

• Pi-hole — 全网络广告拦截
• Model Context Protocol — 用于 AI 工具集成的开放标准
• MCP Server Registry — MCP 服务目录

许可证

MIT