金大哥 - homelab-mcp MCP 详情

article

README

🚀 家用实验室MCP服务器

通过Claude Desktop管理家用实验室基础设施的模型上下文协议（MCP）服务器。

这是一组用于通过Claude Desktop管理和监控家用实验室基础设施的模型上下文协议（MCP）服务器。

🚀 快速开始

1. 克隆仓库

git clone https://github.com/bjeans/homelab-mcp
cd homelab-mcp

2. 安装安全检查（推荐）

# 安装预推送git钩子以进行自动安全验证
python helpers/install_git_hook.py

3. 设置配置文件

环境变量：

# Windows
copy .env.example .env

# Linux/Mac
cp .env.example .env

编辑 .env 文件并填入实际值：

# Windows
notepad .env

# Linux/Mac
nano .env

Ansible清单（如果使用）：

# Windows
copy ansible_hosts.example.yml ansible_hosts.yml

# Linux/Mac
cp ansible_hosts.example.yml ansible_hosts.yml

编辑文件并填入基础设施详细信息。 项目说明：

# Windows
copy PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md

# Linux/Mac
cp PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md

根据网络拓扑和服务器进行自定义。 AI开发指南自定义（可选）：

# Windows
copy CLAUDE_CUSTOM.example.md CLAUDE_CUSTOM.md

# Linux/Mac
cp CLAUDE_CUSTOM.example.md CLAUDE_CUSTOM.md

根据实际服务器名称和基础设施详细信息进行自定义。此文件已被git忽略，可让Claude了解你的特定家用实验室设置。有关本地自定义的更多信息，请参阅 CLAUDE.md。

4. 安装Python依赖项

pip install -r requirements.txt

5. 添加到Claude Desktop配置

配置文件位置：

Windows：%APPDATA%\Claude\claude_desktop_config.json
macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Linux：~/.config/Claude/claude_desktop_config.json

选项A：统一服务器（推荐） 所有家用实验室服务器的单个条目：

{
  "mcpServers": {
    "homelab-unified": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    }
  }
}

注意： 统一服务器包含7个MCP服务器：Ansible、Docker、Ping、Ollama、Pi-hole、Unifi、UPS。已弃用的mcp-registry-inspector不包含在内。

选项B：单个服务器（旧版） 每个服务器的单独条目：

{
  "mcpServers": {
    "docker": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\docker_mcp_podman.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    },
    "ollama": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\ollama_mcp.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    },
    "pihole": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\pihole_mcp.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    },
    "unifi": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\unifi_mcp_optimized.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    },
    "ping": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\ping_mcp_server.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    },
    "ups-monitor": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\ups_mcp_server.py"],
      "env": {
        "ANSIBLE_INVENTORY_PATH": "C:\\Path\\To\\ansible_hosts.yml"
      }
    }
  }
}

注意： 不同模式下的工具名称不同。有关详细信息，请参阅 MIGRATION.md。此示例中已移除已弃用的mcp-registry-inspector。Ansible MCP服务器集成跟踪在 #39。

6. 重启Claude Desktop

7. 将项目说明添加到Claude

复制自定义的 PROJECT_INSTRUCTIONS.md 文件的内容
粘贴到Claude项目的“项目说明”字段中
这将为Claude提供有关MCP功能的全面上下文

✨ 主要特性

通过Claude Desktop管理和监控家用实验室基础设施。
提供灵活的部署选项，包括统一服务器和单个服务器模式。
支持多种MCP服务器，如Ansible、Docker、Ollama等。
具备动态工具参数枚举功能，方便配置和使用。
包含自动化安全检查，保障项目安全。

📦 安装指南

系统要求

Python：3.10或更高版本
Claude Desktop：建议使用最新版本
网络访问：能够连接到家用实验室服务

Python依赖项

通过 requirements.txt 安装：

pip install -r requirements.txt

核心依赖项：

mcp - 模型上下文协议SDK
aiohttp - 异步HTTP客户端
pyyaml - 用于Ansible清单的YAML解析

服务要求

Docker/Podman：受监控主机上启用API
Pi-hole：v6+ 并启用API
Unifi Controller：启用API访问
Ollama：运行实例并可访问API
NUT（网络UPS工具）：安装并配置在带有UPS设备的主机上
Ansible：清单文件（可选但推荐）

💻 使用示例

基础用法

# 示例代码保持不变
# 克隆仓库
git clone https://github.com/bjeans/homelab-mcp
cd homelab-mcp

# 安装安全检查
python helpers/install_git_hook.py

# 设置环境变量
copy .env.example .env
notepad .env  # 编辑.env文件

# 安装Python依赖项
pip install -r requirements.txt

# 添加到Claude Desktop配置
# 根据实际情况选择统一服务器或单个服务器模式

高级用法

# 高级场景说明 - 使用Docker部署
# 拉取最新镜像
docker pull bjeans/homelab-mcp:latest

# 运行容器
docker run -d \
  --name homelab-mcp \
  --network host \
  -v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
  bjeans/homelab-mcp:latest

📚 详细文档

本项目包含多个针对不同受众的文档文件：

README.md （本文档） - 安装、设置和使用指南
MIGRATION.md - v2.0统一服务器的迁移指南
PROJECT_INSTRUCTIONS.md - 复制到Claude项目说明中，为AI提供上下文
CLAUDE.md - AI助手和贡献者的开发指南
SECURITY.md - 安全策略和最佳实践
CONTRIBUTING.md - 如何为该项目做出贡献
CHANGELOG.md - 版本历史和变更记录

👥 对于最终用户： 遵循本README并将 PROJECT_INSTRUCTIONS.md 复制到Claude中 🔄 从v1.x迁移？ 请参阅 MIGRATION.md 以了解统一服务器的迁移方法 🤖 对于AI助手： 阅读 CLAUDE.md 以获取完整的开发上下文 🔧 对于贡献者： 从 CONTRIBUTING.md 和 CLAUDE.md 开始

🔧 技术细节

部署选项

版本2.2.0 提供了两种模式和两种方法的灵活部署：

部署模式

选择MCP服务器的组织方式：

1. 统一服务器（推荐）

在单个进程中运行所有MCP服务器，并使用命名空间工具。这是新安装的推荐方法，并且是Docker部署所必需的。

{
  "mcpServers": {
    "homelab-unified": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\homelab_unified_mcp.py"]
    }
  }
}

优点：

✅ 单个配置条目
✅ 所有服务器使用一个Python进程
✅ 日志更清晰（无重复警告）
✅ 所有工具使用命名空间（例如，docker_get_containers，ping_ping_host）
✅ Docker部署必需
✅ 内置健康检查
✅ 适合生产环境的容器化

2. 单个服务器（旧版，完全支持）

将每个MCP服务器作为单独的进程运行。此模式为向后兼容而完全支持，并且仅适用于原生Python安装。

{
  "mcpServers": {
    "docker": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\docker_mcp_podman.py"]
    },
    "ollama": {
      "command": "python",
      "args": ["C:\\Path\\To\\Homelab-MCP\\ollama_mcp.py"]
    }
  }
}

优点：

✅ 对每个服务器进行精细控制
✅ 可以单独启用/禁用服务器
✅ 原始工具名称（例如，get_docker_containers，ping_host）
✅ 与v1.x向后兼容

注意： 不同模式下的工具名称不同。有关详细的迁移说明和工具名称更改，请参阅 MIGRATION.md。

部署方法

选择安装和运行服务器的方式：

1. Docker容器（推荐用于生产环境）

Docker Hub上提供预构建的镜像，可立即部署。有关完整的设置说明，请参阅 🐳 Docker部署。 快速开始：

docker pull bjeans/homelab-mcp:latest
docker-compose up -d

优点：

✅ 无需设置Python环境
✅ 预构建、经过测试的镜像
✅ 通过拉取镜像自动更新
✅ 多平台支持（amd64，arm64）
✅ 简化配置
✅ 适合生产环境的容器化

限制：

仅支持统一服务器模式
mcp-registry-inspector不可用（已弃用）

2. 原生Python安装（开发和旧版）

直接安装Python依赖项并从源代码运行服务器。有关完整的设置说明，请参阅 📦 安装指南。 优点：

✅ 完全访问源代码
✅ 易于调试和开发
✅ 支持统一和单个服务器模式
✅ 可在任何支持Python的平台上运行

要求：

Python 3.10+ 并安装pip
手动管理依赖项
通过 .env 文件进行环境配置

迁移指南： 有关在不同模式或方法之间切换的详细说明，请参阅 MIGRATION.md。

可用的MCP服务器

✨ 动态工具参数枚举（v2.1.0新增）

当你配置Ansible清单时，Claude Desktop将自动在下拉菜单中显示你的基础设施选项。无需再猜测主机名或组名！ 自动填充的内容：

Ping工具 - 你的Ansible组将显示在下拉菜单中
Docker工具 - 你的Docker/Podman主机将显示在下拉菜单中
Ollama工具 - 你的Ollama服务器主机名可供选择
UPS工具 - 你的NUT服务器主机名将显示在下拉菜单中

工作原理：

在 .env 文件中设置 ANSIBLE_INVENTORY_PATH
重启Claude Desktop（必需 - 枚举在启动时加载）
使用工具时，Claude将在下拉菜单中显示你的实际基础设施，而无需手动输入

重要注意事项：

需要重启： 对Ansible清单的更改需要重启Claude Desktop以更新下拉选项
性能： 枚举在启动时生成一次 - 即使使用大型清单（100+主机），影响也很小
优雅降级： 如果未配置Ansible清单，工具仍然可以正常工作 - 只是不会显示下拉建议

示例前后对比： 之前： "我应该ping哪个组？" → 用户手动输入 "webservers"（或猜测） 之后： "我应该ping哪个组？" → 用户从下拉菜单中选择：all，docker_hosts，webservers，databases 等。

故障排除：

下拉菜单未显示？ 验证 ANSIBLE_INVENTORY_PATH 是否设置并重启Claude Desktop
显示错误的选项？ 检查你的Ansible清单是否是最新的并重启Claude Desktop
性能问题？ 枚举在启动时生成一次 - 如果速度较慢，请检查清单文件大小和Ansible安装

MCP注册表检查器（⚠️ 已弃用）

弃用通知（v2.3.0）： 此工具已弃用。Claude Desktop现在具有原生文件系统访问权限，因此此MCP服务器不再必要。你可以直接要求Claude读取你的MCP服务器文件或配置。

替代方法： 使用Claude的内置文件访问功能：

"读取我的claude_desktop_config.json文件"
"显示docker_mcp_podman.py的源代码"
"列出此目录中的所有 .py 文件"

对于现有配置的用户： 此服务器将继续工作，但不会接收更新。它将在v3.0.0中从文档中移除。建议从你的 claude_desktop_config.json 中移除它。

旧版配置（仅供参考）

工具：

get_claude_config - 查看Claude Desktop MCP配置
list_mcp_servers - 列出所有注册的MCP服务器
list_mcp_directory - 浏览MCP开发目录
read_mcp_file - 读取MCP服务器源代码
write_mcp_file - 写入/更新MCP服务器文件
search_mcp_files - 按名称搜索文件

配置：

MCP_DIRECTORY=/path/to/your/Homelab-MCP
CLAUDE_CONFIG_PATH=/path/to/claude_desktop_config.json  # 可选

Docker/Podman容器管理器

跨多个主机管理Docker和Podman容器。 🔒 安全警告： Docker/Podman API通常使用未加密的HTTP且无身份验证。有关必需的防火墙配置，请参阅 SECURITY.md。 工具： 单个服务器模式：

get_docker_containers - 获取特定主机上的容器
get_all_containers - 获取所有主机上的所有容器
get_container_stats - 获取CPU和内存统计信息
check_container - 检查特定容器是否正在运行
find_containers_by_label - 按标签查找容器
get_container_labels - 获取容器的所有标签

统一服务器模式（使用命名空间）：

docker_get_containers - 获取特定主机上的容器
docker_get_all_containers - 获取所有主机上的所有容器
docker_get_container_stats - 获取CPU和内存统计信息
docker_check_container - 检查特定容器是否正在运行
docker_find_containers_by_label - 按标签查找容器
docker_get_container_labels - 获取容器的所有标签

配置选项： 选项1：使用Ansible清单（推荐）

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml

# Ansible清单组名（默认：docker_hosts，podman_hosts）
# 如果你在ansible_hosts.yml中使用不同的组名，请更改这些值
DOCKER_ANSIBLE_GROUP=docker_hosts
PODMAN_ANSIBLE_GROUP=podman_hosts

选项2：使用环境变量

DOCKER_SERVER1_ENDPOINT=192.168.1.100:2375
DOCKER_SERVER2_ENDPOINT=192.168.1.101:2375
PODMAN_SERVER1_ENDPOINT=192.168.1.102:8080

Ollama AI模型管理器

监控和管理家用实验室中的Ollama AI模型实例，并检查LiteLLM代理以实现统一的API访问。

包含内容

Ollama监控：

跟踪不同主机上的多个Ollama实例
查看可用模型及其大小
检查实例的健康状况和可用性

LiteLLM代理集成：

LiteLLM为所有Ollama实例提供统一的OpenAI兼容API
支持在多个Ollama服务器之间进行负载均衡和故障转移
允许你使用OpenAI客户端库与本地模型进行交互
MCP服务器可以验证你的LiteLLM代理是否在线并响应

为什么使用LiteLLM？

负载均衡：自动在多个Ollama实例之间分配请求
故障转移：如果一个Ollama服务器出现故障，请求将路由到健康的服务器
OpenAI兼容性：可以使用任何OpenAI SDK/库与本地模型进行交互
集中访问：所有模型使用单个端点（例如，http://192.0.2.10:4000）
使用跟踪：监控哪些模型使用最多

工具：

get_ollama_status - 检查所有Ollama实例的状态和模型数量
get_ollama_models - 获取特定主机的详细模型列表
get_litellm_status - 验证LiteLLM代理是否在线并响应

配置选项： 选项1：使用Ansible清单（推荐）

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
OLLAMA_PORT=11434  # 默认Ollama端口

# Ansible清单组名（默认：ollama_servers）
# 如果你在ansible_hosts.yml中使用不同的组名，请更改此值
OLLAMA_INVENTORY_GROUP=ollama_servers

# LiteLLM配置
LITELLM_HOST=192.168.1.100  # 运行LiteLLM代理的主机
LITELLM_PORT=4000           # LiteLLM代理端口（默认：4000）

选项2：使用环境变量

# Ollama实例
OLLAMA_SERVER1=192.168.1.100
OLLAMA_SERVER2=192.168.1.101
OLLAMA_WORKSTATION=192.168.1.150

# LiteLLM代理
LITELLM_HOST=192.168.1.100
LITELLM_PORT=4000

设置LiteLLM（可选）： 如果你想使用LiteLLM实现对Ollama实例的统一访问：

在其中一台服务器上安装LiteLLM：

pip install litellm[proxy]

创建配置文件 (litellm_config.yaml)：

model_list:
  - model_name: llama3.2
    litellm_params:
      model: ollama/llama3.2
      api_base: http://server1:11434
  - model_name: llama3.2
    litellm_params:
      model: ollama/llama3.2
      api_base: http://server2:11434

router_settings:
  routing_strategy: usage-based-routing

启动LiteLLM代理：

litellm --config litellm_config.yaml --port 4000

使用MCP工具验证其是否正在运行：

在Claude中："检查我的LiteLLM代理状态"

示例用法：

"我有哪些正在运行的Ollama实例？"
"显示我的Dell-Server上的所有模型"
"我的LiteLLM代理是否在线？"
"所有服务器上有多少个可用模型？"

Pi-hole DNS管理器

监控Pi-hole DNS统计信息和状态。 🔒 安全注意事项： 将Pi-hole API密钥安全地存储在 .env 文件中。为每个实例生成唯一的密钥。 工具：

get_pihole_stats - 获取所有Pi-hole实例的DNS统计信息
get_pihole_status - 检查哪些Pi-hole实例在线

配置选项： 选项1：使用Ansible清单（推荐）

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml

# Ansible清单组名（默认：PiHole）
# 如果你在ansible_hosts.yml中使用不同的组名，请更改此值
PIHOLE_ANSIBLE_GROUP=PiHole

# .env文件中仍需要API密钥：
PIHOLE_API_KEY_SERVER1=your-api-key-here
PIHOLE_API_KEY_SERVER2=your-api-key-here

选项2：使用环境变量

PIHOLE_API_KEY_SERVER1=your-api-key
PIHOLE_API_KEY_SERVER2=your-api-key
PIHOLE_SERVER1_HOST=pihole1.local
PIHOLE_SERVER1_PORT=80
PIHOLE_SERVER2_HOST=pihole2.local
PIHOLE_SERVER2_PORT=8053

获取Pi-hole API密钥：

网页界面：设置 → API → 显示API令牌
或者生成新密钥：在Pi-hole服务器上运行 pihole -a -p

Unifi网络监控器

监控Unifi网络基础设施和客户端，并使用缓存以提高性能。 🔒 安全注意事项： 使用具有最小所需权限的专用API密钥。 工具：

get_network_devices - 获取所有网络设备（交换机、AP、网关）
get_network_clients - 获取所有活动网络客户端
get_network_summary - 获取网络概述
refresh_network_data - 强制从控制器刷新数据（绕过缓存）

配置：

UNIFI_API_KEY=your-unifi-api-key
UNIFI_HOST=192.168.1.1

注意： 数据缓存5分钟以提高性能。使用 refresh_network_data 强制更新。

Ansible清单检查器

查询Ansible清单信息（只读）。在统一和独立模式下均可用。 统一模式工具（带有 ansible_ 前缀）：

ansible_get_all_hosts - 获取清单中的所有主机
ansible_get_all_groups - 获取所有组
ansible_get_host_details - 获取详细的主机信息
ansible_get_group_details - 获取详细的组信息
ansible_get_hosts_by_group - 获取特定组中的主机
ansible_search_hosts - 按模式或变量搜索主机
ansible_get_inventory_summary - 高级清单概述
ansible_reload_inventory - 从磁盘重新加载清单

独立模式工具（无前缀）：

get_all_hosts - 获取清单中的所有主机
get_all_groups - 获取所有组
get_host_details - 获取详细的主机信息
get_group_details - 获取详细的组信息
get_hosts_by_group - 获取特定组中的主机
search_hosts - 按模式或变量搜索主机
get_inventory_summary - 高级清单概述
reload_inventory - 从磁盘重新加载清单

配置：

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml

部署：

✅ 统一服务器模式可用
✅ Docker部署可用
✅ 独立模式可用：python ansible_mcp_server.py

Ping网络连接监控器

使用ICMP ping测试整个基础设施中的网络连接和主机可用性。 为什么使用此工具？

在停电或电源事件后进行快速健康检查
在查询特定服务的MCP之前验证哪些主机可达
简单的故障排除工具，用于识别网络问题
对基础设施进行基线连接测试

工具：

ping_host - 按名称ping单个主机（从Ansible清单中解析）
ping_group - 同时pingAnsible组中的所有主机
ping_all - 同时ping整个基础设施中的所有主机
list_groups - 列出可用于ping操作的Ansible组

特性：

✅ 跨平台支持 - 在Windows、Linux和macOS上均可使用
✅ Ansible集成 - 自动从清单中解析主机名/IP
✅ 并发ping - 同时测试多个主机以获得更快的结果
✅ 详细统计信息 - RTT最小值/平均值/最大值、丢包百分比
✅ 可定制 - 配置超时和数据包数量
✅ 无依赖项 - 使用系统 ping 命令（无需额外库）

配置：

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
# 无需额外的API密钥！

示例用法：

"ping server1.example.local"
"检查所有Pi-hole服务器的连接性"
"ping所有Ubuntu_Server主机"
"测试整个基础设施的连接性"
"我可以ping哪些组？"

使用时机：

停电后 - 快速识别哪些主机已恢复在线
服务检查前 - 在检查特定服务之前验证主机是否可达
网络故障排除 - 将连接问题与服务问题隔离
健康监控 - 定期检查以确保基础设施的可用性

UPS监控（网络UPS工具）

使用网络UPS工具（NUT）协议监控整个基础设施中的UPS（不间断电源）设备。 为什么使用此工具？

实时了解电源基础设施状态
在停电期间电池耗尽之前进行主动警报
监控不同主机上的多个UPS设备
跟踪电池健康状况和运行时间估计
对于关键基础设施规划至关重要

工具：

get_ups_status - 检查所有NUT服务器上的所有UPS设备的状态
get_ups_details - 获取特定UPS设备的详细信息
get_battery_runtime - 获取所有UPS设备的电池运行时间估计
get_power_events - 检查最近的电源事件（使用电池、低电量）
list_ups_devices - 列出清单中配置的所有UPS设备
reload_inventory - 更改后重新加载Ansible清单

特性：

✅ NUT协议支持 - 使用网络UPS工具标准协议（端口3493）
✅ Ansible集成 - 自动从清单中发现UPS
✅ 每台主机多个UPS - 支持带有多个UPS设备的服务器
✅ 电池监控 - 跟踪充电水平、剩余运行时间、负载百分比
✅ 电源事件检测 - 识别UPS何时切换到电池或电量低
✅ 跨平台 - 适用于任何与NUT兼容的UPS（TrippLite、APC、CyberPower等）
✅ 灵活认证 - 可选的用户名/密码认证

配置： 选项1：使用Ansible清单（推荐）

ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml

# 默认NUT端口（可选，默认为3493）
NUT_PORT=3493

# NUT认证（可选 - 仅当你的NUT服务器需要时）
NUT_USERNAME=monuser
NUT_PASSWORD=secret

Ansible清单示例：

nut_servers:
  hosts:
    dell-server.example.local:
      ansible_host: 192.168.1.100
      nut_port: 3493
      ups_devices:
        - name: tripplite
          description: "TrippLite SMART1500LCDXL"

选项2：使用环境变量

NUT_PORT=3493
NUT_USERNAME=monuser
NUT_PASSWORD=secret

先决条件：

在带有UPS设备的主机上安装NUT：

# Debian/Ubuntu
sudo apt install nut nut-client nut-server

# RHEL/Rocky/CentOS
sudo dnf install nut nut-client

配置NUT守护进程 (/etc/nut/ups.conf)：

[tripplite]
    driver = usbhid-ups
    port = auto
    desc = "TrippLite SMART1500LCDXL"

启用网络监控 (/etc/nut/upsd.conf)：

LISTEN 0.0.0.0 3493

配置访问权限 (/etc/nut/upsd.users)：

[monuser]
    password = secret
    upsmon master

启动NUT服务：

sudo systemctl enable nut-server nut-client
sudo systemctl start nut-server nut-client

示例用法：

"我所有UPS设备的状态如何？"
"显示Dell服务器UPS的电池运行时间"
"检查是否有任何电源事件"
"获取TrippLite UPS的详细信息"
"列出所有配置的UPS设备"

使用时机：

电源闪烁后 - 验证UPS设备是否正确处理了事件
维护前 - 检查电池电量和估计运行时间
定期监控 - 跟踪UPS健康状况和电池状态
容量规划 - 了解系统在电池供电下可以运行多长时间

常见UPS状态代码：

OL - 在线（正常运行，有AC电源）
OB - 使用电池（停电，使用电池运行）
LB - 低电量（电池电量极低，即将关机）
CHRG - 充电中（电池正在充电）
RB - 更换电池（电池需要更换）

🔒 安全

自动化安全检查

本项目包含自动化安全验证，以防止意外暴露敏感数据： 安装预推送git钩子（推荐）：

# 从项目根目录运行
python helpers/install_git_hook.py

它的作用：

在每次git push之前自动运行 helpers/pre_publish_check.py
阻止包含潜在秘密或敏感数据的推送
防止意外提交API密钥、密码或个人信息

手动安全检查：

# 手动运行安全验证
python helpers/pre_publish_check.py

绕过安全检查（谨慎使用）：

# 仅在绝对必要时使用
git push --no-verify

关键安全实践

配置文件：

✅ 务必使用 .env.example 作为模板
✅ 务必限制 .env 文件的权限（在Linux/Mac上使用 chmod 600）
❌ 切勿将 .env 提交到版本控制
❌ 切勿提交包含实际基础设施的 ansible_hosts.yml
❌ 切勿提交包含实际网络拓扑的 PROJECT_INSTRUCTIONS.md

API安全：

✅ 务必为每个服务使用唯一的API密钥
✅ 务必定期轮换API密钥（建议每90天一次）
✅ 务必使用强随机生成的密钥（32个字符以上）
❌ 切勿将Docker/Podman API暴露到互联网
❌ 切勿在不同环境中重复使用API密钥

网络安全：

✅ 务必使用防火墙规则限制API访问
✅ 务必实施VLAN分段
✅ 务必在可能的情况下启用TLS/HTTPS
❌ 切勿公开暴露管理接口

有关详细的安全指南，请参阅 SECURITY.md

📚 额外资源

MCP协议

📄 许可证

本项目采用MIT许可证 - 有关详细信息，请参阅 LICENSE 文件。

🤝 贡献

欢迎贡献！有关详细指南，请参阅 CONTRIBUTING.md。

对于AI助手和开发者

📖 首次贡献？ 首先阅读 CLAUDE.md - 此文件包含：

完整的项目架构和开发模式
安全要求和常见陷阱避免
添加功能和修复漏洞的特定工作流程
处理此代码库的AI助手特定指南

贡献者快速开始

安装安全git钩子 (python helpers/install_git_hook.py)
查看 SECURITY.md 中的安全指南
提交中不包含敏感数据（钩子将自动阻止）
所有配置 使用环境变量或Ansible
更新文档 以反映任何更改
使用实际基础设施进行彻底测试

拉取请求流程

分叉仓库
创建功能分支 (git checkout -b feature/amazing-feature)
进行更改
使用你的家用实验室设置进行测试
根据需要更新README和其他文档
使用清晰的消息提交 (git commit -m 'Add amazing feature')
推送到你的分叉 (git push origin feature/amazing-feature)
打开拉取请求

代码审查标准

遵循安全最佳实践
无硬编码的凭据或IP地址
正确的错误处理
代码遵循现有模式
文档清晰完整
更改经过测试

🙏 致谢

Anthropic 提供Claude和MCP
家用实验室社区提供灵感
贡献者和测试者

📞 支持

问题反馈：GitHub问题
讨论交流：GitHub讨论
安全问题：有关报告漏洞的信息，请参阅 SECURITY.md

请记住：本项目涉及关键基础设施。请始终优先考虑安全，并先在安全的环境中测试更改！

homelab-mcp

README

🚀 家用实验室MCP服务器

🚀 快速开始

1. 克隆仓库

2. 安装安全检查（推荐）

3. 设置配置文件

4. 安装Python依赖项

5. 添加到Claude Desktop配置

6. 重启Claude Desktop

7. 将项目说明添加到Claude

✨ 主要特性

📦 安装指南

系统要求

Python依赖项

服务要求

💻 使用示例

基础用法

高级用法

📚 详细文档

🔧 技术细节

部署选项

部署模式

1. 统一服务器（推荐）

2. 单个服务器（旧版，完全支持）

部署方法

1. Docker容器（推荐用于生产环境）

2. 原生Python安装（开发和旧版）

可用的MCP服务器

✨ 动态工具参数枚举（v2.1.0新增）

MCP注册表检查器（⚠️ 已弃用）

Docker/Podman容器管理器

Ollama AI模型管理器

包含内容

Pi-hole DNS管理器

Unifi网络监控器

Ansible清单检查器

Ping网络连接监控器

UPS监控（网络UPS工具）

🔒 安全

自动化安全检查

关键安全实践

📚 额外资源

MCP协议

相关项目

📄 许可证

🤝 贡献

对于AI助手和开发者

贡献者快速开始

拉取请求流程

代码审查标准

🙏 致谢

📞 支持

运行方式说明

托管运行

本地运行 / 其它方式