PiHole MCP Server

Pi-hole MCP 服务

---

这是一个用 Java 实现的 Pi-hole MCP（Model Control Protocol）服务，可让 AI 应用通过标准命令与 Pi-hole 实例交互并进行管理。

功能

• 核心 AI 工具
  • Restart Pi-hole FTL Service — 重启 Pi-hole FTL DNS 服务以应用更改或恢复服务。
  • Get Pi-hole DNS Blocking Status — 获取当前的拦截模式和剩余时间。
  • Set Pi-hole DNS Blocking Status — 启用／停用 DNS 拦截；也可设置停用时长（秒）。
  • Add New Domain — 将域名添加到允许列表／拒绝列表（支持 exact 和 regex 类型），并进行验证；也可添加备注。
  • Retrive Pi-hole Statistics — 获取统计数据，如查询总数、拦截的查询数和热门域名。
  • Retrive Pi-hole System Information — 获取系统信息，包括 CPU 负载、内存使用量、拦截百分比和运行时间。

运行服务

要运行 MCP 服务，机器上需要安装 Java 21。

1. 从发布页面下载 Pi-hole MCP 服务 JAR 文件。
2. 在 AI 应用客户端中添加 MCP 服务配置。

JSON 配置示例：

{
  "mcpServers": {
    "pihole-mcp-server-java": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/pihole-mcp.jar"
      ],
      "env": {
        "PIHOLE_PORT": "8080",
        "PIHOLE_HOST": "192.168.1.2",
        "PIHOLE_APP_PASSWORD": "your_app_password"
      }
    }
  }
}

YAML 配置示例：

name: pihole-mcp-server-java
version: 0.0.1
schema: v1
mcpServers:
  - name: pihole-mcp-server-java
    command: java
    args:
      - -jar
      - /absolute/path/to/pihole-mcp.jar
    env: {
      "PIHOLE_PORT": "8080",
      "PIHOLE_HOST": "192.168.1.2",
      "PIHOLE_APP_PASSWORD": "your_app_password"
    }

环境变量

请确保设置以下环境变量：

• PIHOLE_PORT：（可选）Pi-hole 实例运行的端口（默认为 80）。
• PIHOLE_HOST：Pi-hole 实例的 IP 地址或主机名。
• PIHOLE_APP_PASSWORD：Pi-hole 实例的应用密码。

从源代码构建

前置条件：

• Java JDK 21
• Maven

按照以下步骤从源代码构建 Pi-hole MCP 服务：

1. 克隆／下载仓库。
2. 使用 Maven 构建项目：

   mvn clean package
   

3. 使用上文提到的命令运行服务。

许可证

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