Pi-hole 的模型上下文协议 (MCP) 服务器。该服务器将 Pi-hole 的功能公开为可供 AI 助手使用的工具。
uv （可选，用于开发）如果要在本地运行应用程序，请使用uv 。使用您选择的包管理器进行安装。
Related MCP server: MCP Pi-hole Server
使用您的 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 服务器：
# Standard deployment
docker-compose up -d该服务器将通过http://localhost:8383访问
对于开发，请使用本地构建的 dev 撰写文件：
docker-compose -f docker-compose.dev.yml up您可以使用uv和mcp CLI 运行 MCP 检查器：
uv run mcp dev main.py这将在http://localhost:6274启动一个交互式界面，您可以在其中测试工具和资源。
该 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 查询。”
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"
]
}
}
}之后，完全重新启动应用程序并尝试一下。
This server cannot be deployed
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
