内容
# pihole-mcp
[](LICENSE)
[](https://nodejs.org)
[](https://pi-hole.net)
[](https://modelcontextprotocol.io)
一个遵循MCP（Model Context Protocol）协议的服务器，为Claude等AI助手提供对Pi-hole v6 DNS广告拦截器的完全控制权，包括查询日志、允许/拒绝列表、组管理、重载gravity和统计信息。设计之初就考虑到了多实例部署：从单个MCP端点管理一个或多个Pi-hole实例。
## 为什么？
Pi-hole的管理API功能强大，但脚本编写起来很麻烦。这个MCP服务器将每个Pi-hole API操作转换为任何与MCP兼容的AI助手可以直接调用的工具。不需要再点击管理UI或编写curl命令，只需询问AI助手即可检查被阻止的内容、允许某个域名或比较实例之间的统计信息。
非常适合运行多个Pi-hole的家庭实验室用户（主要+次要，或每个VLAN一个）、在规模上管理DNS过滤的网络管理员，以及任何想要AI辅助DNS管理的人。
## 功能
- **多实例支持** - 通过环境变量配置1到N个Pi-hole实例
- **完整的Pi-hole v6 API覆盖** - 查询日志、允许/拒绝列表、组管理、重载gravity、统计信息
- **智能正则表达式检测** - 自动根据元字符分析将域名路由到精确或正则表达式列表
- **正则表达式雷区检测器** - 查找应该使用正则表达式但被错误分类的拒绝-精确条目（miscategorized规则）
- **Docker-ready** - 多阶段Dockerfile，包含非root用户、健康检查和安全强化
- **可流式HTTP传输** - 与任何支持基于HTTP的MCP的MCP客户端配合使用
- **Docker secrets支持** - 通过环境变量或/run/secrets/文件传递密码
## 快速开始
### Docker（推荐）
```bash
git clone https://github.com/ranklancer/pihole-mcp.git
cd pihole-mcp
cp .env.example .env
# 编辑.env文件，填写你的Pi-hole URL和密码
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
```bash
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](.env.example)获取完整参考。
### 单实例
```env
PIHOLE_INSTANCES=pihole
PIHOLE_BASE_URL=http://192.0.2.100
PIHOLE_PASSWORD=your-password
```
### 多实例
```env
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` | 获取查询日志，支持过滤（限制、时间范围、客户端、域名、状态） |
| `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_check_regex_types` | 检测拒绝-精确列表中的错误分类正则表达式 |
每个工具都接受一个可选的`instance`参数，以针对特定的Pi-hole。默认为第一个配置的实例。
## 连接到您的MCP客户端
服务器监听`http://HOST:PORT/mcp`（默认为`http://localhost:3000/mcp`）。
### Claude Desktop / Claude Code
在您的MCP设置中添加：
```json
{
"mcpServers": {
"pihole": {
"url": "http://localhost:3031/mcp"
}
}
}
```
### Supergateway（stdio包装器）
如果您的MCP客户端仅支持stdio传输，请使用[supergateway](https://github.com/supercorp-ai/supergateway)：
```bash
npx -y supergateway --streamableHttp http://localhost:3031/mcp
```
## 健康检查
```bash
curl http://localhost:3031/health
# {"ok":true,"service":"pihole-mcp","version":"0.2.0"}
```
## 开发
```bash
npm install
npm run dev # 监视模式 — 重新编译
npm start # 运行服务器
```
## 要求
- Node.js >= 20
- Pi-hole v6，已启用API访问
- 与您的Pi-hole实例的网络连接
## 相关项目
- [Pi-hole](https://pi-hole.net) — 网络范围的广告拦截
- [Model Context Protocol](https://modelcontextprotocol.io) — AI工具集成的开放标准
- [MCP Server Registry](https://github.com/modelcontextprotocol/servers) — MCP服务器目录
## 许可证
MIT
