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 許可證。