MCP Server Pihole

Pi hole MCP服务器

一个MCP（模型上下文协议）服务器，提供与Pi-hole的API交互的工具。

 ](https://hub.docker.com/r/lazybaer/pihole-mcp-server)

备注：此服务器旨在与 便于部署和管理。

特性

公共API工具（无需身份验证）

• get_pihole_status -检查Pi孔是否启用/禁用
• get_pihole_summary -获取统计摘要
• get_query_types -获取DNS查询类型细分
• get_forward_destinations -获取上游DNS服务器信息
• get_top_items -获取查询最多的域名
• get_top_clients -按查询计数获取顶级客户端
• get_top_blocked_domains -获取被屏蔽的顶级域名
• get_recent_blocked -获取最近被屏蔽的域名

管理员API工具（需要API密钥）

• enable_pihole -启用Pi孔堵塞
• disable_pihole -禁用Pi孔堵塞（暂时）
• add_to_whitelist / remove_from_whitelist -管理白名单
• add_to_blacklist / remove_from_blacklist -管理黑名单
• get_whitelist / get_blacklist -查看列表
• flush_logs -清除Pi孔日志
• get_tail_log -获取最近的日志条目

安装和配置

Docker快速入门（推荐）

1. 克隆此存储库并复制环境模板：

   git clone https://github.com/cwdcwd/mcp-server-pihole.git
   cd mcp-server-pihole
   cp .env.example .env

1. 编辑 .env 带上你的Pi孔细节：

   PIHOLE_BASE_URL=http://pihole.local  # Your Pi-hole URL
   PIHOLE_PASSWORD=your_admin_password  # Required for admin functions

1. 使用Docker Compose运行：

   npm run docker:compose

地方发展设置

1. 安装依赖项并构建：

   npm install
   npm run build

1. 在开发模式下运行：

   npm run dev

获取Pi hole管理员密码

在Pi hole设置中找到您的管理员密码，或重置密码：

# On your Pi-hole device
sudo pihole -a -p

使用Claude Desktop

将此服务器添加到您的Claude Desktop MCP配置中：

配置文件位置

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

配置示例

{
  "mcpServers": {
    "pihole": {
      "command": "node",
      "args": ["/path/to/pihole-mcp-server/dist/index.js"],
      "env": {
        "PIHOLE_BASE_URL": "http://pihole.local",
        "PIHOLE_PASSWORD": "your_admin_password"
      }
    }
  }
}

查询示例

配置后，您可以询问Claude：

• “我的Pi孔的状态如何？”
• “显示被屏蔽的顶级域名”
• “将facebook.com添加到黑名单”
• “禁用Pi孔5分钟”

Docker使用

Docker Compose（推荐）

npm run docker:compose      # Start with compose
npm run docker:compose:down # Stop

手动Docker命令

npm run docker:build  # Build image
npm run docker:run    # Run container

MCP网关集成

对于Docker MCP网关，请使用提供的 mcp-config.json:

{
  "mcpServers": {
    "pihole": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", ".env", "pihole-mcp-server"]
    }
  }
}

故障排除

常见问题

• 连接问题：确保Pi孔可接近（尝试 ping pihole.local)
• 身份验证问题：验证您的管理员密码是否正确
• Docker网络问题：使用 host.docker.internal 而不是 localhost 如有需要
• 权限问题：管理员操作需要 PIHOLE_PASSWORD

api参考

此服务器包装Pi-hole的API，该API记录在： Pi-hole API文档

所有响应都包含JSON格式的原始Pi-hole API响应数据。

代码架构

为了更好的可维护性，这个项目被组织成模块化的TypeScript文件：

源结构

src/
├── index.ts       # Main entry point and configuration
├── types.ts       # TypeScript interfaces and type definitions  
├── constants.ts   # Application constants and enums
├── client.ts      # Pi-hole API client implementation
├── tools.ts       # MCP tool definitions
├── handler.ts     # Tool execution handler  
└── server.ts      # MCP server setup and initialization

关键组件

• PiHoleClient (client.ts)-通过身份验证、重试逻辑和错误处理来处理所有Pi-hole API通信
• PiHoleToolHandler (handler.ts)-将MCP工具调用映射到客户端方法并格式化响应
• PiHoleMCPServer (server.ts)-使用请求处理程序设置MCP服务器
• 工具定义 (tools.ts)-定义按类别组织的所有可用MCP工具
• 配置 (index.ts)-加载环境变量并启动服务器

构建过程

TypeScript源代码在 dist/ 目录：

npm run build  # Compiles TypeScript to dist/
npm start      # Runs the compiled JavaScript

🤝 贡献

我们欢迎捐款！请查看我们的 贡献指南 有关以下内容的详细信息：

• 建立开发环境
• 运行测试
• 提交拉取请求
• 报告错误

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🔗 MCP注册表

此服务器旨在与 The server.yaml 该文件包含注册表提交所需的配置。