JinDaGe - mcp-pihole MCP Details

article

README

🚀 MCP Pi-hole 服务器

MCP（模型上下文协议）服务器，可将 Claude 等 AI 助手连接到你的 Pi-hole 全网广告拦截器。通过自然语言管理 DNS 拦截、查看统计信息、控制白名单/黑名单等。

🚀 快速开始

如果你在网络中运行 Pi-hole，此 MCP 服务器允许你：

监控 DNS 流量：查看查询统计信息、顶级被拦截域名和客户端活动。
控制拦截：立即启用/禁用 Pi-hole 拦截，或设置定时器。
管理列表：无需打开 Web 界面，即可在白名单和黑名单中添加或删除域名。
查看查询日志：查看包含详细信息的近期 DNS 查询。
维护 Pi-hole：更新重力（拦截列表）并刷新 DNS 缓存。

✨ 主要特性

| 类别 | 工具 | |------|------| | 统计信息 | 查询总数、拦截百分比、顶级域名、顶级客户端 | | 拦截控制 | 启用、禁用（可选定时器）、检查状态 | | 域名列表 | 白名单/黑名单的增删改查操作 | | 查询日志 | 包含客户端、状态、响应时间的近期 DNS 查询 | | 维护 | 更新重力、刷新缓存 | | 可视化 | 带有 ANSI 颜色的 ASCII 艺术仪表盘和条形图 |

📦 安装指南

选项 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 桌面版

添加到你的 Claude 桌面版配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%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 代码版

添加到 ~/.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-hole Web 界面 URL | http://pihole.local:8080 | | PIHOLE_PASSWORD | Pi-hole 应用密码 | 你从设置中获取的应用密码 |

可用工具

统计信息

pihole_get_stats - 获取全面的 Pi-hole 统计信息。
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 转义码的终端中显示）

开发

# 在开发模式下运行（自动重新加载）
npm run watch

# 为生产环境构建
npm run build

# 运行构建后的版本
node dist/index.js

故障排除

"PIHOLE_URL 和 PIHOLE_PASSWORD 环境变量是必需的"

确保在你的 MCP 配置中设置了这两个环境变量。

"身份验证失败"

你的应用密码无效或已过期。从 Pi-hole 设置 > API 生成新的密码。

"API 请求失败：401"

会话已过期。服务器将自动重新进行身份验证，但如果问题仍然存在，请检查你的密码。

连接被拒绝

确保 Pi-hole 正在运行，并且 URL 正确。检查你是否可以从你的机器访问 Pi-hole Web 界面。

💻 使用示例

配置完成后，你可以通过自然语言与 Pi-hole 进行交互：

查看统计信息

"显示 Pi-hole 统计信息"

"顶级被拦截域名有哪些？"

"哪些客户端发起的查询最多？"

控制拦截

"Pi-hole 拦截是否已启用？"

"禁用 Pi-hole 5 分钟"

"重新启用 Pi-hole 拦截"

管理域名列表

"将 example.com 添加到白名单"

"阻止 ads.trackersite.com"

"显示所有白名单域名"

查看查询日志

"显示最后 50 条 DNS 查询"

"我的手机查询了哪些域名？"

可视化仪表盘

"显示带有可视化的 Pi-hole 统计信息"

"获取带有可视化的顶级被拦截域名"

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE。