AI导哈

Pi-hole MCP服务器

一个将Pi-hole功能暴露为AI助手可用工具的模型上下文协议(MCP)服务器。

  • by sbarbett
  • Python
  • 本地部署
  • 10 星标
  • 更新于
在 GitHub 查看 sbarbett/pihole-mcp-server

使用说明

🍓 皮孔mcp serer

Pi hole的模型上下文协议（MCP）服务器。该服务器将Pi hole功能作为AI助手可以使用的工具公开。

依赖项

码头工人

uv （可选，用于开发）

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

环境

创建一个 .env 使用您的Pi孔凭据在项目根目录中创建文件：

# 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检查员

您可以使用以下命令运行MCP检查器 uv 和那个 mcp CLI：

uv run mcp dev main.py

这将在以下位置启动交互式界面 http://localhost:6274 在那里你可以测试工具和资源。

API

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

资源

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

工具

每个工具调用都会返回一个字典列表，其结构如下：

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

配置

  • list_local_dns：列出Pi孔中的所有本地DNS设置
  • add_local_a_record：将本地a记录添加到Pi孔。
  • add_local_cname_record：将本地CNAME记录添加到Pi孔。
  • remove_local_a_record：删除主机名的所有A记录。
  • remove_local_cname_record：删除主机名的所有CNAME记录。

指标

  • list_queries：从Pi孔获取最近的DNS查询历史记录
  • list_query_suggestions：获取查询筛选器建议
  • list_query_history：获取查询随时间变化的活动图数据

测试中 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的桌面客户端目前仅支持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"
      ]
    }
  }
}

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

许可证

麻省理工学院

相关 MCP