MCP Pihole

🚀 MCP Pi-hole 服務器

MCP（模型上下文協議）服務器，可將 Claude 等 AI 助手連接到你的 Pi-hole 全網廣告攔截器。通過自然語言管理 DNS 攔截、查看統計信息、控制白名單/黑名單等。

🚀 快速開始

如果你在網絡中運行 Pi-hole，此 MCP 服務器允許你：

• 監控 DNS 流量：查看查詢統計信息、頂級被攔截域名和客戶端活動。
• 控制攔截：立即啟用/禁用 Pi-hole 攔截，或設置定時器。
• 管理列表：無需打開 Web 界面，即可在白名單和黑名單中添加或刪除域名。
• 查看查詢日誌：查看包含詳細信息的近期 DNS 查詢。
• 維護 Pi-hole：更新重力（攔截列表）並刷新 DNS 緩存。

✨ 主要特性

📦 安裝指南

選項 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 應用密碼

1. 打開你的 Pi-hole Web 界面。
2. 轉到設置 > API。
3. 生成新的應用密碼。
4. 複製密碼（僅顯示一次）。

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_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 參數：

使用方法

將 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。

🔗 鏈接

• Pi-hole
• Pi-hole 文檔
• 模型上下文協議
• MCP 規範