🍓 pihole-mcp-server

一个用于Pi-hole的模型上下文协议（MCP）服务器。此服务器将Pi-hole的功能暴露为工具，这些工具可以被AI助手使用。

依赖项

Docker

• Docker安装指南

uv（可选，用于开发）

如果你想在本地运行应用程序，请使用uv。你可以通过你喜欢的包管理器来安装它。

环境

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

# 主Pi-hole（必需）
PIHOLE_URL=https://your-pihole.local/
PIHOLE_PASSWORD=your-admin-password
#PIHOLE_NAME=Primary        # 可选，默认为URL

# 次Pi-hole（可选）
#PIHOLE2_URL=https://secondary-pihole.local/
#PIHOLE2_PASSWORD=password2
#PIHOLE2_NAME=Secondary     # 可选

# 最多4个Pi-hole：
#PIHOLE3_URL=...
#PIHOLE3_PASSWORD=...
#PIHOLE3_NAME=...

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

项目结构

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

/
├── main.py                # 主应用入口点
├── tools/                 # 按功能组织的Pi-hole工具
│   ├── __init__.py
│   ├── config.py          # 与配置相关的工具（DNS设置）
│   └── metrics.py         # 与度量和查询相关的工具
├── resources/             # MCP资源
│   ├── __init__.py
│   └── common.py          # 公共资源（piholes://, version://）
├── docker-compose.yml     # 生产环境的Docker Compose配置
├── docker-compose.dev.yml # 开发环境的Docker Compose配置，带有卷挂载
└── Dockerfile             # Docker构建配置

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

运行服务器

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

使用Docker（推荐用于生产）

# 标准部署
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名称",
    "data": [...]  # 此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 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参数。例如：

{
  8383/sse",
        "--allow-http"
      ]
    }
  }
}

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

许可证

MIT