mcp-pihole

Name: mcp-pihole
Author: aplaceforallmystuff

本地服务

github.com/aplaceforallmystuff安全811 周前更新

代码仓库

关于 mcp-pihole

mcp-pihole 将 MCP 客户端连接到 Pi-hole v6，用于监控 DNS、控制拦截和管理域名列表。它还提供查询日志、维护操作和可选的终端风格可视化。

主要功能

01查看 DNS 统计及热门域名或客户端
02启用或定时关闭拦截
03管理白名单和黑名单域名
04查看近期 DNS 查询日志
05更新 gravity 并清空 DNS 缓存
06生成可选 ASCII 图表和仪表板

适用场景

01检查被拦截域名和客户端活动
02在指定时长内暂停 DNS 拦截
03将域名加入或移出允许及拦截列表

MCP 相关

MCP 服务提供 Pi-hole 统计、拦截控制、域名列表、查询日志和维护工具。它使用 Pi-hole v6 的 URL 和应用密码连接实例。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "aplaceforallmystuff-mcp-pihole": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-pihole-server"
      ],
      "env": {
        "PIHOLE_URL": "<PIHOLE_URL>",
        "PIHOLE_PASSWORD": "<PIHOLE_PASSWORD>"
      }
    }
  }
}

启动命令npx -y mcp-pihole-server

需要配置的环境变量

PIHOLE_URLPi-hole web interface URL (e.g., http://pihole.local:8080)

PIHOLE_PASSWORD密钥Pi-hole app password for API authentication

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmmcp-pihole-server1.0.1stdio

工具

收录的工具列表 · 更新于 2 周前

此工具无需参数。

详细介绍

MCP Pi-hole 服务器

一个 MCP（Model Context Protocol）服务，可将 Claude 等 AI 助手连接到你的 Pi-hole 全网广告拦截器。通过自然语言管理 DNS 拦截、查看统计数据、控制白名单／黑名单等。

为什么要使用它？

如果你在网络中运行 Pi-hole，这个 MCP 服务可以让你：

监控 DNS 流量 - 查看查询统计数据、拦截次数最多的域名和客户端活动
控制拦截 - 立即启用／停用 Pi-hole 拦截，或设置计时器
管理列表 - 无需打开 Web UI，即可在白名单和黑名单中添加或移除域名
查看查询日志 - 查看包含详细信息的近期 DNS 查询
维护 Pi-hole - 更新 gravity（拦截列表）并清空 DNS 缓存

功能

类别	工具
统计数据	查询总数、拦截百分比、热门域名、热门客户端
拦截控制	启用、停用（可选计时器）、检查状态
域名列表	白名单／黑名单 CRUD 操作
查询日志	近期 DNS 查询，包含客户端、状态、响应时间
维护	更新 gravity、清空缓存
可视化	ASCII 艺术仪表板和 ANSI 颜色条形图

先决条件

Node.js 18+
已启用 API 的 Pi-hole v6
Pi-hole 应用密码（在 Pi-hole 设置中生成）
你的计算机可通过网络访问 Pi-hole

安装

选项 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 界面
前往 Settings > API
生成新的应用密码
复制密码（它只会显示一次）

2. 配置 MCP 客户端

用于 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件：

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 Code

添加到 ~/.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 应用密码	你在设置中获取的应用密码

使用示例

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

查看统计数据

“显示 Pi-hole 统计数据”

“拦截次数最多的域名有哪些？”

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

控制拦截

“Pi-hole 是否已启用拦截？”

“停用 Pi-hole 5 分钟”

“重新启用 Pi-hole 拦截”

管理域名列表

“将 example.com 添加到白名单”

“拦截 ads.trackersite.com”

“显示所有白名单域名”

查看查询日志

“显示最近 50 条 DNS 查询”

“我的手机查询过哪些域名？”

可视化仪表板

“显示 Pi-hole 统计数据，并设置 visualize: true”

“以可视化形式获取拦截次数最多的域名”

可用工具

统计数据

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 - 更新屏蔽列表（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-hole 正在运行且 URL 正确。检查能否从你的计算机访问 Pi-hole Web 界面。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。

许可证

MIT 许可证 - 详情请参阅 LICENSE。

链接

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。