pihole-mcp-serer

一个为 Pi-hole 设计的模型上下文协议 (MCP) 服务器。该服务器将 Pi-hole 功能作为工具暴露出来，可供 AI 助手使用。

特性

• ListLocalDNS: 返回来自 Pi-hole 的所有本地 DNS 设置
• ListQueries: 返回来自 Pi-hole 的最近 DNS 查询历史
• 多 Pi-hole 支持: 通过单个 MCP 服务器管理多达 4 个 Pi-holes
• ...更多即将推出...

依赖项

Docker

• Docker 安装指南

uv（可选，用于开发）

如果你想在本地运行应用程序，请使用 uv。使用你选择的包管理器安装它。

环境

在项目根目录下创建一个 .env 文件，并填入你的 Pi-hole 凭证：

# Primary Pi-hole (required)
PIHOLE_URL=https://your-pihole.local/
PIHOLE_PASSWORD=your-admin-password
#PIHOLE_NAME=Primary        # optional, defaults to URL if unset

# Secondary Pi-hole (optional)
#PIHOLE2_URL=https://secondary-pihole.local/
#PIHOLE2_PASSWORD=password2
#PIHOLE2_NAME=Secondary     # optional

# Up to 4 Pi-holes:
#PIHOLE3_URL=...
#PIHOLE3_PASSWORD=...
#PIHOLE3_NAME=...

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

项目结构

该项目遵循模块化组织以提高可维护性：

/
├── main.py                # Main application entry point
├── tools/                 # Pi-hole tools organized by functionality
│   ├── __init__.py
│   ├── config.py          # Configuration-related tools (DNS settings)
│   └── metrics.py         # Metrics and query-related tools
├── resources/             # MCP resources
│   ├── __init__.py
│   └── common.py          # Common resources (piholes://, version://)
├── docker-compose.yml     # Docker Compose configuration for production
├── docker-compose.dev.yml # Docker Compose for development with volume mounts
└── Dockerfile             # Docker build configuration

这种结构将代码分为逻辑组件，同时保持与所有运行模式的兼容性。

运行服务器

有几种方法可以运行 Pi-hole MCP 服务器：

使用 Docker（推荐用于生产环境）

# Standard deployment
docker-compose up -d

服务器将在 http://localhost:8383 上可用。

开发模式下的 Docker

对于开发，使用开发版 compose 文件，它会设置卷挂载以便实时代码更改：

# Development mode with live reloading
docker-compose -f docker-compose.dev.yml up

本地开发

对于本地开发，你可以直接用 uv 运行服务器：

# Interactive development UI (recommended for development)
uv run mcp dev main.py

这将以 http://localhost:6274 启动一个交互式的 MCP 开发环境，在这里你可以测试工具和资源。

要直接运行服务器：

# Run the server directly (HTTP/SSE mode)
uv run python main.py

CLI 模式（STDIO）

为了与使用 STDIO 协议的 MCP 客户端集成（如 Claude Desktop）：

# Run as an MCP STDIO server
uv run mcp run main.py

注意： 服务器使用 stderr 进行日志记录，以避免干扰 STDIO 协议。任何日志消息将出现在终端中，但不会中断 MCP 通信。

API

此 MCP 服务器公开了以下资源和工具：

资源

• piholes://: 返回关于所有配置的 Pi-holes 的信息

工具

• list_local_dns: 列出来自 Pi-hole(s) 的所有本地 DNS 设置
• list_queries: 从 Pi-hole(s) 获取最近的 DNS 查询历史

每个工具调用返回的结果是一个字典列表，具有如下结构：

[
  {
    "pihole": "Pi-hole Name",
    "data": [...]  # Result data from this Pi-hole
  },
  ...
]

在 goose 中测试

Goose 是一个有用的 CLI LLM 客户端，适用于测试和开发。请按照此处的安装说明进行操作。

假设你已经完成了初始设置 goose configure。

配置扩展

1. 输入 goose configure 打开配置菜单。
2. 选择 添加扩展
3. 选择 远程扩展
4. 它会询问名称。命名无所谓。我将其命名为 pihole-mcp。
5. 当被问及 "SSE 端点 URI 是什么？" 时，输入 http://localhost:8383/sse。
6. 输入超时时间。
7. 如果愿意的话，可以添加描述。
8. 当它询问是否有关于环境变量的问题时，选择 否。
   

开始会话

一旦服务器安装完毕，就可以开始聊天会话了。

goose session

试着问它："我的本地DNS记录是什么？"

...或者告诉它："显示我最近的DNS查询。"

Claude 桌面版

Claude 的桌面客户端目前仅支持 STDIO 协议，但你可以使用代理与 SSE 端点进行通信。

在你的 claude_desktop_config.json 文件中添加以下内容。

{
  "mcpServers": {
    "pihole": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8383/sse"
      ]
    }
  }
}

如果你连接的是本地网络中的不同主机，并且使用的是不安全的连接，则需要通过 --allow-http 参数明确允许。例如：

{
  "mcpServers": {
    "pihole": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://192.168.1.255:8383/sse",
        "--allow-http"
      ]
    }
  }
}

之后，完全重启应用程序并尝试使用。

许可证

MIT