🍓 pihole-mcp-serer

🍓 pihole-mcp-serer

Pi-hole 的模型上下文协议（MCP）服务。此服务将 Pi-hole 功能作为工具提供，供 AI 助手使用。

依赖项

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 的开发模式

开发时，使用会在本地构建的 dev compose 文件：

docker-compose -f docker-compose.dev.yml up

MCP Inspector

你可以使用 uv 和 mcp CLI 运行 MCP Inspector：

uv run mcp dev main.py

这将在 http://localhost:6274 启动一个交互式界面，你可以在其中测试工具和资源。

API

此 MCP 服务提供以下资源和工具：

资源

• piholes://：返回所有已配置 Pi-hole 的信息
• version://：返回 MCP 服务版本
• list-tools://：返回工具类别列表
  • list-tools://{category}：返回指定类别中的工具列表

工具

每次工具调用都会以字典列表的形式返回结果，结构如下：

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

配置

• list_local_dns：列出所有 Pi-hole 中的本地 DNS 设置
• add_local_a_record：向 Pi-hole 添加本地 A 记录。
• add_local_cname_record：向 Pi-hole 添加本地 CNAME 记录。
• remove_local_a_record：移除某个主机名的所有 A 记录。
• remove_local_cname_record：移除某个主机名的所有 CNAME 记录。

指标

• list_queries：获取 Pi-hole 中最近的 DNS 查询历史记录
• list_query_suggestions：获取查询筛选建议
• list_query_history：获取一段时间内查询活动图表的数据

在 goose 中测试

Goose 是一个适用于测试和开发的 CLI 大模型客户端。请按照这里的安装说明操作。

以下内容假设你已通过 goose configure 完成初始设置。

配置扩展

1. 输入 goose configure 打开配置菜单。
2. 选择 Add Extension
3. 选择 Remote Extension
4. 系统会要求输入名称。名称随意。我将它命名为 pihole-mcp。
5. 当系统询问 "What is the SSE endpoint URI?" 时，输入 http://localhost:8383/sse。
6. 输入超时时间。
7. 如有需要，添加描述。
8. 当系统询问环境变量时，选择 No。

开始会话

安装服务后，启动一个聊天会话。

goose session

试着询问它："我的本地 DNS 记录有哪些？"

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

Claude Desktop

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