Pi-hole MCP 服务器

🍓 pihole-mcp-服务器

Pi-hole 的模型上下文协议 (MCP) 服务器。该服务器将 Pi-hole 的功能公开为可供 AI 助手使用的工具。

依赖项

Docker

Docker 安装指南

`uv` （可选，用于开发）

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

环境

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

# 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 撰写文件：

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

MCP 检查器

您可以使用uv和mcp CLI 运行 MCP 检查器：

uv run mcp dev main.py

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

API

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

资源

piholes:// ：返回有关所有已配置的 Pi-holes 的信息
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 LLM 客户端，适用于测试和开发。请按照此处的安装说明进行操作。

下面假设您已经使用goose configure完成了初始设置。

配置扩展

输入goose configure打开配置菜单。
选择**“添加扩展”**
选择远程分机
它会要求输入一个名称。随便你叫什么。我把它命名为pihole-mcp 。
当它询问*“SSE 端点 URI 是什么？”*时，输入http://localhost:8383/sse 。
输入超时。
如果您愿意，可以添加描述。
当询问环境变量时，选择**“否”** 。

开始会话

服务器安装完成后，开始聊天会话。

goose session

尝试询问它： “我的本地 DNS 记录是什么？”

本地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"
      ]
    }
  }
}

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

Claude DNS 信息

克劳德查询信息

执照

麻省理工学院

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

将 Pi-hole 功能公开为 AI 助手工具的服务器，允许他们通过自然语言检索本地 DNS 设置和查询历史记录。

Related MCP Servers

Roam Research
2b3pro
A
security
A
license
A
quality
Provides comprehensive access to Roam Research's API functionality. This server enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface.
Last updated -
18
11
58
TypeScript
MIT License
MCP Server
tcpipuk
-
security
A
license
-
quality
A server that enables AI assistants like Claude to safely run Python code and access websites, processing data for better AI understanding while providing helpful error messages.
Last updated -
3
Python
GPL 3.0
Domain-MCP
rinadelph
-
security
A
license
-
quality
A simple MCP server that enables AI assistants to perform domain research including availability checking, WHOIS lookups, DNS record retrieval, and finding expired domains without requiring API keys.
Last updated -
26
Python
MIT License
Polarsteps MCP Server
remuzel
-
security
A
license
-
quality
A server that enables AI assistants to access Polarsteps travel data, allowing queries about user profiles, trip details, travel statistics, and natural language search through travel histories.
Last updated -
2
Python
MIT License

View all related MCP servers

Pi-hole MCP Server