pihole-mcp-server

🚀 🍓 Pi-hole MCP 服务器

Pi-hole MCP 服务器是专为 Pi-hole 打造的 Model Context Protocol (MCP) 服务器。它将 Pi-hole 的各项功能以工具形式开放，方便 AI 助手调用，极大拓展了 Pi-hole 的使用场景。

🚀 快速开始

要使用 Pi-hole MCP 服务器，你需要完成依赖项安装、环境配置，然后选择合适的方式启动服务器。

✨ 主要特性

• 把 Pi-hole 功能以工具形式暴露，便于 AI 助手调用。
• 支持多 Pi-hole 配置，可同时管理多个 Pi-hole 实例。
• 提供清晰的 API 接口，方便开发者集成和使用。

📦 安装指南

依赖项

Docker

你可以参考 Docker 安装指南 来安装 Docker。

uv（可选，用于开发）

若要在本地运行应用程序，可使用 uv，通过你的包管理器进行安装。

环境配置

在项目根目录下创建一个 .env 文件，用于配置 Pi-hole 凭据，示例如下：

# 主 Pi-hole（必需）
PIHOLE_URL=https://your-pihole.local/
PIHOLE_PASSWORD=your-admin-password
#PIHOLE_NAME=Primary        # 可选，默认为 URL 如果未设置

# 次要 Pi-hole（可选）
#PIHOLE2_URL=https://secondary-pihole.local/
#PIHOLE2_PASSWORD=password2
#PIHOLE2_NAME=Secondary     # 可选

# 最多 4 个 Pi-hole：
#PIHOLE3_URL=...
#PIHOLE3_PASSWORD=...
#PIHOLE3_NAME=...

#PIHOLE4_URL=...
#PIHOLE4_PASSWORD=...
#PIHOLE4_NAME=...

项目结构

• src/：存放项目的源代码文件。
• public/：包含构建后的静态资源，如 HTML、CSS 和 JavaScript 文件。

运行服务器

使用 Docker 运行

1. 确保 Docker 已安装并处于运行状态。
2. 在项目根目录创建 .env 文件，配置 Pi-hole 凭据。
3. 执行以下命令构建并运行容器：

docker-compose up --build

使用 Node.js 运行

1. 确保已安装 Node.js 和 npm。
2. 安装项目依赖：

npm install

3. 启动服务器：

npm start

💻 使用示例

基础用法

获取所有 Pi-hole 的信息

curl http://localhost:3000/api/pi-holes

调用工具

调用名为 check-dns-records 的工具：

curl -X POST http://localhost:3000/api/tools/check-dns-records \
  -H "Content-Type: application/json" \
  -d '{"piHoleUrl": "https://your-pihole.local/"}'

📚 详细文档

API 文档

资源

• /api/pi-holes：获取所有 Pi-hole 的信息。
  • 方法：GET
  • 响应：包含所有 Pi-hole 的详细信息，包括 URL 和状态。

工具

• /api/tools：获取所有可用工具的列表。
  • 方法：GET
  • 响应：包含工具的名称和描述。

📄 许可证

本项目采用 MIT 许可证。