使用说明
MCP Pi孔服务器
一个MCP（模型上下文协议）服务器，将Claude等人工智能助手连接到您的 Pi孔 网络广告拦截器。通过自然语言管理DNS阻止、查看统计数据、控制白名单/黑名单等。
为什么使用这个？
如果你在网络上运行Pi hole，这个MCP服务器可以让你：
- 监控DNS流量 -查看查询统计信息、最受阻止的域和客户端活动
- 控制阻塞 -立即或使用计时器启用/禁用Pi孔堵塞
- 管理列表 -在不打开web UI的情况下从白名单和黑名单中添加或删除域
- 查看查询日志 -查看最近DNS查询的详细信息
- 保持你的Pi孔 -更新重力（阻止列表）并刷新DNS缓存
特性
| 类别 | 工具 |
|---|---|
| 统计 | 查询总数、阻止百分比、顶级域、顶级客户端 |
| 阻塞控制 | 启用、禁用（带可选定时器）、检查状态 |
| 域名列表 | 白名单/黑名单CRUD操作 |
| 查询日志 | 最近的DNS查询，包括客户端、状态、响应时间 |
| 维护 | 更新重力，刷新缓存 |
| 可视化 | ANSI颜色的ASCII艺术仪表板和条形图 |
先决条件
- Node.js 18+
- Pi孔 启用API的v6
- Pi hole应用程序密码（在Pi hole设置中生成）
- 从您的机器访问Pi孔的网络
安装
选项1：从npm安装（推荐）
npx mcp-pihole-server
或全局安装：
npm install -g mcp-pihole-server
选项2：克隆和构建
git clone https://github.com/aplaceforallmystuff/mcp-pihole.git
cd mcp-pihole
npm install
npm run build
配置
1.获取您的Pi hole应用程序密码
- 打开您的Pi hole web界面
- 前往“设置”>“API”
- 生成新的应用程序密码
- 复制密码（只显示一次）
2.配置您的MCP客户端
适用于克劳德桌面
添加到您的Claude Desktop配置文件中：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"pihole": {
"command": "npx",
"args": ["-y", "mcp-pihole-server"],
"env": {
"PIHOLE_URL": "http://your-pihole-address:8080",
"PIHOLE_PASSWORD": "your-app-password"
}
}
}
}
克劳德代码
添加到 ~/.claude.json:
{
"mcpServers": {
"pihole": {
"command": "npx",
"args": ["-y", "mcp-pihole-server"],
"env": {
"PIHOLE_URL": "http://your-pihole-address:8080",
"PIHOLE_PASSWORD": "your-app-password"
}
}
}
}
环境变量
| 变量 | 描述 | 示例 |
|---|---|---|
PIHOLE_URL |
Pi孔web界面URL | http://pihole.local:8080 |
PIHOLE_PASSWORD |
Pi hole应用程序密码 | 设置中的应用程序密码 |
使用示例
配置后，您可以通过自然语言与Pi hole交互：
查看统计信息
“显示Pi洞统计数据”
“被屏蔽的顶级域名是什么？”
“哪些客户提出的问题最多？”
控制阻塞
“Pi孔堵塞是否启用？”
“禁用Pi孔5分钟”
“重新启用Pi孔封堵”
管理域列表
“将example.com添加到白名单”
“屏蔽ads.trackersite.com”
“显示所有白名单域名”
查看查询日志
“显示最近50个DNS查询”
“我的手机一直在查询哪些域名？”
可视化仪表板
“用visualize:true显示Pi洞统计数据”
“通过可视化获取被屏蔽的顶级域名”
可用工具
统计
pihole_get_stats-获取全面的Pi孔统计数据pihole_get_top_blocked-获取被屏蔽的顶级域名pihole_get_top_permitted-获取允许的顶级域名pihole_get_top_clients-按查询计数获取顶级客户端pihole_get_query_log-获取最近的DNS查询
阻塞控制
pihole_get_blocking_status-检查是否启用了阻止pihole_enable_blocking-启用DNS阻止pihole_disable_blocking-禁用阻塞（可选配定时器）
域管理
pihole_get_whitelist-列出所有白名单域名pihole_get_blacklist-列出所有被列入黑名单的域名pihole_add_to_whitelist-将域添加到白名单pihole_add_to_blacklist-将域名添加到黑名单pihole_remove_from_whitelist-从白名单中删除域pihole_remove_from_blacklist-从黑名单中删除域
维护
pihole_update_gravity-更新阻止列表（重力）pihole_flush_cache-刷新DNS缓存
ASCII可视化
此服务器支持使用ANSI转义码直接在终端中呈现的彩色ASCII艺术可视化。
支持的工具
以下工具支持可选 visualize: true 参数：
| 工具 | 可视化 |
|---|---|
pihole_get_stats |
完整的仪表板，包含汇总统计数据、顶级客户端、被阻止的域和允许的域 |
pihole_get_top_blocked |
被屏蔽域名的红色条形图 |
pihole_get_top_permitted |
允许域的绿色条形图 |
pihole_get_top_clients |
客户活动蓝色柱状图 |
用法
通过 visualize: true 任何支持的工具：
{
"name": "pihole_get_stats",
"arguments": {
"visualize": true
}
}
当 visualize 未设置或 false，工具像往常一样返回JSON数据。
输出示例
╔════════════════════════════════════════════════════════════════════════════╗
║ 🛡️ PI-HOLE DASHBOARD ║
╠════════════════════════════════════════════════════════════════════════════╣
║ ║
║ 📊 SUMMARY ║
║ ────────────────────────────────────────────────────────────────────────── ║
║ Total Queries: 73K Domains Blocked: 2.4M ║
║ Blocked: 22K Active Clients: 28 ║
║ Block Rate: 29.7% Total Clients: 115 ║
╠════════════════════════════════════════════════════════════════════════════╣
║ 🔝 TOP CLIENTS ║
║ ────────────────────────────────────────────────────────────────────────── ║
║ 192.168.1.52 ████████████████████████████████████████ 28K (38%) ║
║ 192.168.1.51 ███████████████████▋ 14K (19%) ║
╚════════════════════════════════════════════════════════════════════════════╝
（颜色显示在支持ANSI转义码的端子中）
发展
# Run in development mode (auto-reloads)
npm run watch
# Build for production
npm run build
# Run the built version
node dist/index.js
故障排除
“PIHOLE_URL和PIHOLE_PASSWORD环境变量是必需的”
确保在MCP配置中设置了这两个环境变量。
“身份验证失败”
您的应用密码无效或已过期。从Pi-hole设置>API生成一个新的。
“API请求失败：401”
会话已过期。服务器将自动重新进行身份验证，但如果问题仍然存在，请检查您的密码。
连接被拒绝
确保Pi孔正在运行并且URL正确。检查您是否可以从机器访问Pi hole web界面。
贡献
欢迎投稿！请查看 贡献.md 作为指导方针。
许可证
MIT许可证-请参阅 许可证 了解详情。
