Homelab MCP服务器
用于通过Claude Desktop管理家庭实验室基础设施的模型上下文协议(MCP)服务器。
一组模型上下文协议(MCP)服务器,用于通过Claude Desktop管理和监控您的家庭实验室基础设施。
🔒 安全通知
⚠️ 重要提示:请阅读 安全.md 在部署此项目之前。
该项目与关键基础设施(Docker API、DNS、网络设备)进行交互。配置不当会使您的家庭实验室面临安全风险。
关键安全要求:
- 切勿将Docker/Podman API暴露于互联网 -使用防火墙规则限制访问
- 保持
.env文件安全 -包含API密钥,不应提交 - 使用唯一的API密钥 -为每个服务生成单独的密钥
- 审查网络安全 -确保正确的VLAN分段和防火墙规则
看 安全.md 以获得全面的安全指导。
文档概述
此项目包括针对不同受众的几个文档文件:
- README.md (此文件)-安装、设置和使用指南
- 迁移率V3.md -v2.0统一服务器迁移指南
- 项目_结构S.md -将AI上下文的项目说明复制到Claude中
- CLAUDE.md -面向AI助手和贡献者的开发人员指南
- 安全.md -安全策略和最佳实践
- 贡献.md -如何为这个项目做出贡献
- 更改日志.md -版本历史和更改
👥 对于最终用户: 按照此自述文件+将PROJECT_INSTRUCTIONS.md复制给Claude
🔄 从v1.x迁移? 看 迁移率V3.md 用于统一服务器迁移
🤖 对于AI助理: 阅读 CLAUDE.md 完整的开发环境
🔧 对于贡献者: 从贡献.md开始 CLAUDE.md
📖 重要提示:配置Claude项目说明
在设置MCP服务器之后, 创建个性化的项目说明:
- 复制示例模板:```bash
Windows
copy PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md
Linux/Mac
cp PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md
1. **编辑文件** 使用您的实际基础设施详细信息:
**项目_结构S.md** (用于Claude Desktop项目说明):
- 用您的真实网络地址替换示例IP地址
- 添加您的实际服务器主机名
- 根据您的特定服务和配置进行定制
- **将此文件保密** -它包含您的网络拓扑
**CLAUDE_CUSTOM.md** (仅适用于人工智能开发工作——贡献者):
- 使用您实际的GitHub存储库更新存储库URL
- 如果使用任务管理,请添加您的Notion工作区URL
- 自定义基础架构参考
- **将此文件保密** -包含您的特定URL和设置
1. **添加到克劳德桌面:**
- 打开克劳德桌面
- 转到项目设置
- 复制您自定义的内容 `PROJECT_INSTRUCTIONS.md`
- 粘贴到“项目说明”字段
**内容包括:**
- 详细的MCP服务器功能和使用模式
- 基础设施概述和监控能力
- 每个服务都有特定的命令和工具
- 故障排除和开发指导
本自述文件涵盖了安装和基本设置。项目说明为Claude提供了全面的使用背景。
## 🎯 部署选项
**版本3.0.0** 提供两种模式和两种方法的灵活部署:
### 部署模式
选择MCP服务器的组织方式:
#### 1.统一服务器(推荐)
使用命名空间工具在单个进程中运行所有MCP服务器。这是新安装和 **Docker部署所必需的**.```json
{
"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安装.```json
{
"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
**注:** 不同模式的工具名称不同。看 迁移率V3.md 有关详细的迁移说明和工具名称更改。
______________________________________________________________________
### 部署方法
选择如何安装和运行服务器:
#### 1.Docker容器(推荐用于生产环境)
Docker Hub上提供的预构建映像可立即部署。看 🐳 Docker部署 有关完整的设置说明。
**快速入门:**```bash
docker pull bjeans/homelab-mcp:latest
docker-compose up -d
优势:
- ✅ 不需要Python环境设置
- ✅ 预构建、经过测试的图像
- ✅ 通过图像拉取自动更新
- ✅ 多平台支持(amd64、arm64)
- ✅ 简化配置
- ✅ 生产级集装箱化
限制:
- 仅支持统一服务器模式
- mcp注册表检查器不可用(已弃用)
2.原生Python安装(开发和遗留)
直接安装Python依赖项并从源代码运行服务器。看 📦 安装 有关完整的设置说明。
快速入门:```bash
pip install -r requirements.txt
python homelab_unified_mcp.py
**优势:**
- ✅ 完全访问源代码
- ✅ 易于调试和开发
- ✅ 支持统一和单独的服务器模式
- ✅ 可以在任何Python兼容的平台上运行
**要求:**
- Python 3.10+带pip
- 手动依赖关系管理
- 通过.env文件进行环境配置
______________________________________________________________________
**迁移指南:** 看 迁移率V3.md 有关在模式或方法之间切换的详细说明。
______________________________________________________________________
## ⚡ FastMCP框架(v3.0.0)
**3.0.0版本使用FastMCP:** 一个现代的MCP框架,简化了服务器架构,同时增加了对多种传输机制和工具注释的支持。
### 什么是FastMCP?
FastMCP是一个轻量级框架,它:
- ✅ 将服务器代码减少38%(消除1754行)
- ✅ 使用简单的装饰图案(`@mcp.tool()`)用于工具定义
- ✅ 包括用于行为提示的全面工具注释
- ✅ 添加对HTTP和SSE传输的支持(除了stdio)
- ✅ 根据Python类型提示自动生成模式
- ✅ 提高代码可维护性,使添加新服务器更容易
**全部39工具** 现在包括MCP注释(`readOnlyHint`, `idempotentHint`等),以帮助Claude就工具使用做出明智的决定。
### 运输选项
FastMCP服务器可以使用不同的传输机制运行:
#### 1.标准输入/输出(stdio)-默认值
Claude Desktop使用的传统MCP传输。这是大多数用户的默认和推荐选项。```bash
# Run with stdio (default)
python homelab_unified_mcp.py
# Or explicitly specify stdio transport
python homelab_unified_mcp.py --transport stdio
何时使用:
- Claude桌面集成(默认模式)
- 最常见的用例
- 无需额外配置
2.HTTP传输
将MCP服务器作为HTTP服务运行,用于远程或灵活部署场景。```bash
Start server with HTTP transport
python homelab_unified_mcp.py --transport http --host 0.0.0.0 --port 8000
Test the HTTP endpoint
curl http://localhost:8000/tools
**何时使用:**
- 远程部署服务器
- 基于Web的集成
- 多客户端场景
- 负载平衡要求
#### 3.服务器发送事件(SSE)传输
用于实时双向通信的基于流的协议。```bash
# Start server with SSE transport
python homelab_unified_mcp.py --transport sse --host 0.0.0.0 --port 8000
# Connect via SSE client
curl http://localhost:8000/sse
何时使用:
- 实时监控应用程序
- 基于浏览器的集成
- 事件驱动架构
- 流媒体响应
使用FastMCP配置Claude桌面
默认情况下,Claude Desktop继续使用stdio传输。无需更改配置:```json
{
"mcpServers": {
"homelab-unified": {
"command": "python",
"args": ["C:\Path\To\Homelab-MCP\homelab_unified_mcp.py"]
}
}
}
### 从v2.2.0迁移
如果您从v2.2.0升级:
- ✅ **没有突破性的变化** -您的现有配置将继续工作,不变
- ✅ **功能相同** -所有7台服务器和所有工具保持不变
- ✅ **更干净的代码** -内部重构产生相同的结果
- ✅ **新选项** -如果需要,可选HTTP/SSE传输可用
无需任何操作-只需更新并重新启动Claude Desktop。
______________________________________________________________________
## 🚀 快速开始
### 1.克隆存储库```bash
git clone https://github.com/bjeans/homelab-mcp
cd homelab-mcp
2.安装安全检查(推荐)```bash
Install pre-push git hook for automatic security validation
python helpers/install_git_hook.py
### 3.设置配置文件
**环境变量:**```bash
# Windows
copy .env.example .env
# Linux/Mac
cp .env.example .env
编辑 .env 根据您的实际值:```bash
Windows
notepad .env
Linux/Mac
nano .env
**可靠库存(如果使用):**```bash
# Windows
copy ansible_hosts.example.yml ansible_hosts.yml
# Linux/Mac
cp ansible_hosts.example.yml ansible_hosts.yml
使用您的基础设施详细信息进行编辑。
项目说明:```bash
Windows
copy PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md
Linux/Mac
cp PROJECT_INSTRUCTIONS.example.md PROJECT_INSTRUCTIONS.md
根据您的网络拓扑和服务器进行自定义。
**人工智能开发指南定制(可选):**```bash
# Windows
copy CLAUDE_CUSTOM.example.md CLAUDE_CUSTOM.md
# Linux/Mac
cp CLAUDE_CUSTOM.example.md CLAUDE_CUSTOM.md
使用您的实际服务器名称和基础架构详细信息进行自定义。此文件是gitignored的,允许Claude了解您的特定家庭实验室设置。看 CLAUDE.md 有关本地自定义的更多信息。
4.安装Python依赖项```bash
pip install -r requirements.txt
### 5.添加到Claude桌面配置
**配置文件位置:**
- **视窗**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
**选项A:统一服务器(推荐)**
所有家庭实验室服务器的单一入口:```json
{
"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/Podman、Ollama、Pi hole、Unifi、UPS和Ping。不包括已弃用的mcp注册表检查器。
选项B:单个服务器(旧版)
每个服务器的单独条目:```json
{
"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"
}
}
}
}
**注:** 不同模式的工具名称不同。看 迁移率V3.md 了解详情。此示例中已删除弃用的mcp注册表检查器。Ansible MCP服务器集成在中跟踪 #39.
### 6.重新启动克劳德桌面
### 7.向Claude添加项目说明
- 复制您自定义的内容 `PROJECT_INSTRUCTIONS.md`
- 粘贴到Claude项目的“项目说明”字段中
- 这为Claude提供了有关您的MCP能力的全面背景
## 🐳 Docker部署(替代方案)
在Docker容器中运行MCP服务器,以便于分发、隔离和生产部署。
**Docker Hub:** b牛仔裤/家庭实验室mcp
### Docker Hub快速入门(最简单)
**预构建的镜像会自动发布到支持多平台的Docker Hub(amd64/arm64):**```bash
# Pull the latest image
docker pull bjeans/homelab-mcp:latest
# Run with your Ansible inventory
docker run -d \
--name homelab-mcp \
--network host \
-v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
bjeans/homelab-mcp:latest
# Or use a specific commit
docker pull bjeans/homelab-mcp:main-17bae01
在Docker Hub上可用: https://hub.docker.com/r/bjeans/homelab-mcp/tags
当前可用的标签:
latest-主分支的最新稳定版本(推荐)edge-主分支机构的最新开发版本main--用于可追溯性的特定提交构建(例如。,main-17bae01)
语义版本标签(发布后可用):
- 版本标签,如
2.2.0,2.2,2将在以下时间创建v2.2.0Git发布 - 在那之前,使用
latest对于最近的稳定版本
多平台支持:
linux/amd64-x86_64服务器和工作站linux/arm64-Raspberry Pi,基于ARM的系统
从源代码构建(高级)
如果需要自定义,请在本地构建映像:```bash
Pull the pre-built image from Docker Hub (recommended)
docker pull bjeans/homelab-mcp:latest
Run with Docker Compose (recommended for production)
docker-compose up -d
Or run unified server directly
docker run -d \
--name homelab-mcp \
--network host \
-v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
bjeans/homelab-mcp:latest
**从源构建(可选):**```bash
# Clone and navigate to repository
git clone https://github.com/bjeans/homelab-mcp
cd homelab-mcp
# Build the image locally
docker build -t homelab-mcp:latest .
Docker功能
2.0.0 Docker改进:
- ✅ 统一MCP服务器作为默认入口点(一个容器中的所有7台服务器)
- ✅ 自动统一模式检测(无需ENABLED_SERVERS)
- ✅ 内置健康检查(配置HEALTHCHECK)
- ✅ 非root用户安全(mcpuser UID 1000)
- ✅ 正确的信号处理和干净的停机
- ✅ 优化层缓存以实现更快的重建
- ✅ 包括系统依赖关系(iputils ping用于跨平台支持)
配置方法
方法1:可靠库存(推荐)```bash
Create your ansible_hosts.yml with infrastructure details
Then mount as volume:
docker run -d \
--name homelab-mcp \
--network host \
-v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
bjeans/homelab-mcp:latest
**方法2:环境变量(市场就绪)**```bash
docker run -d \
--name homelab-mcp \
--network host \
-e DOCKER_SERVER1_ENDPOINT=192.168.1.100:2375 \
-e DOCKER_SERVER1_NAME=Local-Docker \
-e OLLAMA_SERVER1_ENDPOINT=192.168.1.100:11434 \
bjeans/homelab-mcp:latest
传统模式:独立服务器(Docker)
为了向后兼容,您仍然可以通过设置来运行单个服务器 ENABLED_SERVERS:```bash
docker run -d \
--name homelab-mcp-docker \
--network host \
-e ENABLED_SERVERS=docker \
-v $(pwd)/ansible_hosts.yml:/config/ansible_hosts.yml:ro \
bjeans/homelab-mcp:latest
### 可用服务器
**统一模式(默认):**
- ✅ 一个进程中的所有7台服务器:Ansible、Docker、Ping、Ollama、Pi hole、Unifi、UPS
- ✅ 命名空间工具(例如。, `ansible_get_all_hosts`, `docker_get_containers`, `ups_get_ups_status`)
- ✅ 单一配置条目
- ✅ 内置健康检查
**传统模式(设置 `ENABLED_SERVERS`):**
- ✅ `ansible` -可回答的库存查询
- ✅ `docker` -Docker/Podman容器管理
- ✅ `ping` -网络ping实用程序
- ✅ `ollama` -Olama人工智能模型管理
- ✅ `pihole` -Pi孔DNS统计
- ✅ `unifi` -Unifi网络设备监控
- ✅ `ups` -UPS/NUT电源监控
### Docker配置
**支持两种配置方法:**
1. **可靠库存(推荐)** -按体积安装
1. **环境变量** -通过Docker传递 `-e` 旗帜
看 医生.md 获取全面的Docker部署指南,包括:
- 详细的设置说明
- 网络配置选项
- 安全最佳实践
- Claude桌面集成
- 常见问题排查
### 与Claude Desktop集成
**统一模式(推荐):**```json
{
"mcpServers": {
"homelab-unified": {
"command": "docker",
"args": ["exec", "-i", "homelab-mcp", "python", "homelab_unified_mcp.py"]
}
}
}
传统模式(单个服务器):```json
{
"mcpServers": {
"homelab-docker": {
"command": "docker",
"args": ["exec", "-i", "homelab-mcp-docker", "python", "docker_mcp_podman.py"]
},
"homelab-ping": {
"command": "docker",
"args": ["exec", "-i", "homelab-mcp", "python", "ping_mcp_server.py"]
}
}
}
**重要提示:** 使用 `docker exec -i` (不是 `-it`)用于正确的MCP stdio通信。
### 测试Docker容器
**快速验证测试(使用环境变量-市场就绪):**```bash
# Test Unified Server
docker run --rm --network host \
-e DOCKER_SERVER1_ENDPOINT=localhost:2375 \
-e OLLAMA_SERVER1_ENDPOINT=localhost:11434 \
bjeans/homelab-mcp:latest
# Test Individual Server (legacy)
docker run --rm --network host \
-e ENABLED_SERVERS=ping \
bjeans/homelab-mcp:latest
Docker编写测试:```bash
docker-compose up -d
docker-compose logs -f
有关全面的Docker部署指南,请参阅 医生.md.
## 📦 可用的MCP服务器
### ✨ 动态刀具参数枚举(v2.1.0中的新功能)
当您配置Ansible资源清册时,Claude Desktop会自动在下拉菜单中显示您的基础设施选项。不再猜测主机名或组名!
**自动填充的内容:**
- **Ping工具** -您的Ansible组出现在下拉菜单中
- **Docker工具** -您的Docker/Podman主机显示在下拉菜单中
- **Ollama工具** -您的Ollama服务器主机名可供选择
- **UPS工具** -您的NUT服务器主机名显示在下拉菜单中
**它是如何工作的:**
1. 集 `ANSIBLE_INVENTORY_PATH` 在你的 `.env` 文件
1. 重新启动Claude Desktop(必需-启动时加载枚举)
1. 使用工具时,Claude在下拉菜单中显示您的实际基础设施,而不需要手动输入
**重要提示:**
- **需要重新启动:** 对Ansible清单的更改需要重新启动Claude Desktop以更新下拉选项
- **演出** 枚举在启动时生成一次-即使有大量库存(100多台主机),影响也很小
- **优雅的退化:** 如果没有配置Ansible库存,工具仍然可以工作——你只是看不到下拉建议
**前/后示例:**
*之前:* “我应该ping哪个组?”→ 用户手动键入“Web服务器”(或猜测)
*之后:* “我应该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_mcpupodman.py的源代码”
- “列出此目录中的所有.py文件”
**对于具有现有配置的用户:** 此服务器将继续工作,但不会接收更新。它将从v3.0.0中的文档中删除。考虑将其从您的 `claude_desktop_config.json`.
Legacy Configuration (for reference only)
**工具:**
- `get_claude_config` -查看克劳德桌面MCP配置
- `list_mcp_servers` -列出所有已注册的MCP服务器
- `list_mcp_directory` -浏览MCP开发目录
- `read_mcp_file` -读取MCP服务器源代码
- `write_mcp_file` -写入/更新MCP服务器文件
- `search_mcp_files` -按名称搜索文件
**配置:**```bash
MCP_DIRECTORY=/path/to/your/Homelab-MCP
CLAUDE_CONFIG_PATH=/path/to/claude_desktop_config.json # Optional
Docker/Podman容器管理器
跨多个主机管理Docker和Podman容器。
🔒 安全警告: Docker/Podman API通常使用未加密的HTTP,无需身份验证。看 安全.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库存(推荐)```bash
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
Ansible inventory group names (default: docker_hosts, podman_hosts)
Change these if you use different group names in your ansible_hosts.yml
DOCKER_ANSIBLE_GROUP=docker_hosts
PODMAN_ANSIBLE_GROUP=podman_hosts
**选项2:使用环境变量**```bash
DOCKER_SERVER1_ENDPOINT=192.168.1.100:2375
DOCKER_SERVER2_ENDPOINT=192.168.1.101:2375
PODMAN_SERVER1_ENDPOINT=192.168.1.102:8080
Olama人工智能模型经理
在您的homeab中监控和管理Ollama AI模型实例,并检查您的LiteLLM代理以获得统一的API访问。
包含内容
奥利玛监测:
- 跨不同主机跟踪多个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库存(推荐)```bash
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
OLLAMA_PORT=11434 # Default Ollama port
Ansible inventory group name (default: ollama_servers)
Change this if you use a different group name in your ansible_hosts.yml
OLLAMA_INVENTORY_GROUP=ollama_servers
LiteLLM Configuration
LITELLM_HOST=192.168.1.100 # Host running LiteLLM proxy
LITELLM_PORT=4000 # LiteLLM proxy port (default: 4000)
**选项2:使用环境变量**```bash
# Ollama Instances
OLLAMA_SERVER1=192.168.1.100
OLLAMA_SERVER2=192.168.1.101
OLLAMA_WORKSTATION=192.168.1.150
# LiteLLM Proxy
LITELLM_HOST=192.168.1.100
LITELLM_PORT=4000
设置LiteLLM(可选):
如果您想使用LiteLLM统一访问Ollama实例:
- 安装litellm 在您的一台服务器上:```bash
pip install litellm[proxy]
1. **创建配置** (`litellm_config.yaml`):```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代理:```bash
litellm --config litellm_config.yaml --port 4000
1. **使用MCP工具** 要验证它是否正在运行:
- 在Claude中:“检查我的LiteLLM代理状态”
**示例用法:**
- “我正在运行哪些Ollama实例?”
- “显示Dell服务器上的所有型号”
- “我的LiteLLM代理是否在线?”
- “所有服务器上有多少种型号可用?”
### Pi hole DNS管理器
监控Pi孔DNS统计数据和状态。
**🔒 安全说明:** 将Pi-hole API密钥安全地存储在 `.env` 文件。为每个实例生成唯一密钥。
**工具:**
- `get_pihole_stats` -从所有Pi hole实例获取DNS统计信息
- `get_pihole_status` -检查哪些Pi孔实例处于联机状态
**配置选项:**
**选项1:使用Ansible库存(推荐)**```bash
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
# Ansible inventory group name (default: PiHole)
# Change this if you use a different group name in your ansible_hosts.yml
PIHOLE_ANSIBLE_GROUP=PiHole
# API keys still required in .env:
PIHOLE_API_KEY_SERVER1=your-api-key-here
PIHOLE_API_KEY_SERVER2=your-api-key-here
选项2:使用环境变量```bash
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密钥:**
- Web UI:设置→ API → 显示API令牌
- 或生成新的: `pihole -a -p` 在Pi hole服务器上
### Unifi网络监视器
使用缓存监控Unifi网络基础设施和客户端的性能。
**🔒 安全说明:** 使用具有最低权限的专用API密钥。
**工具:**
- `get_network_devices` -获取所有网络设备(交换机、AP、网关)
- `get_network_clients` -获取所有活动网络客户端
- `get_network_summary` -获取网络概述
- `refresh_network_data` -从控制器强制刷新(绕过缓存)
**配置:**```bash
UNIFI_API_KEY=your-unifi-api-key
UNIFI_HOST=192.168.1.1
注: 数据缓存5分钟以提高性能。使用 refresh_network_data 强制更新。
可靠的库存检查员
查询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-从磁盘重新加载库存
配置:```bash
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
**部署:**
- ✅ 在统一服务器模式下可用
- ✅ 在Docker部署中可用
- ✅ 可在独立模式下使用: `python ansible_mcp_server.py`
### Ping网络连接监视器
在您的基础设施中使用ICMP ping测试网络连接和主机可用性。
**为什么要用这个?**
- 停电期间或电力事件后的快速健康检查
- 在查询特定于服务的MCP之前,验证哪些主机是可访问的
- 简单的故障排除工具,用于识别网络问题
- 基础设施的基线连接测试
**工具:**
- `ping_host` -按名称Ping单个主机(从Ansible清单解析)
- `ping_group` -同时Ping Ansible组中的所有主机
- `ping_all` -同时Ping所有基础架构主机
- `list_groups` -列出可用于ping操作的Ansible组
**特征:**
- ✅ **与跨平台支持** -适用于Windows、Linux和macOS
- ✅ **可靠的集成** -自动解析清单中的主机名/IP
- ✅ **并发ping** -同时测试多台主机以获得更快的结果
- ✅ **详细统计** -RTT最小值/平均值/最大值,丢包率
- ✅ **可定制的** -配置超时和数据包计数
- ✅ **无依赖** -使用系统 `ping` 命令(不需要额外的库)
**配置:**```bash
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
# No additional API keys required!
示例用法:
- “Ping服务器1.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)
- ✅ 可靠的集成 -从库存中自动发现UPS
- ✅ 每台主机配备多台UPS -支持具有多个UPS设备的服务器
- ✅ 电池监控 -跟踪充电水平、剩余运行时间、负载百分比
- ✅ 电源事件检测 -识别UPS何时切换到电池或电池电量低
- ✅ 跨平台 -适用于任何NUT兼容的UPS(TrippLite、APC、CyberPower等)
- ✅ 灵活的身份验证 -可选用户名/密码身份验证
配置:
选项1:使用Ansible库存(推荐)```bash
ANSIBLE_INVENTORY_PATH=/path/to/ansible_hosts.yml
Default NUT port (optional, defaults to 3493)
NUT_PORT=3493
NUT authentication (optional - only if your NUT server requires it)
NUT_USERNAME=monuser
NUT_PASSWORD=secret
**合理的库存示例:**```yaml
nut_servers:
hosts:
dell-server.example.local:
ansible_host: 192.168.1.100
nut_port: 3493
ups_devices:
- name: tripplite
description: "TrippLite SMART1500LCDXL"
选项2:使用环境变量```bash
NUT_PORT=3493
NUT_USERNAME=monuser
NUT_PASSWORD=secret
**先决条件:**
1. **在配备UPS设备的服务器上安装NUT:**```bash
# Debian/Ubuntu
sudo apt install nut nut-client nut-server
# RHEL/Rocky/CentOS
sudo dnf install nut nut-client
- 配置NUT守护进程(
/etc/nut/ups.conf):```ini
[tripplite]
driver = usbhid-ups
port = auto
desc = "TrippLite SMART1500LCDXL"
1. **启用网络监控(`/etc/nut/upsd.conf`):**```ini
LISTEN 0.0.0.0 3493
- 配置访问权限(
/etc/nut/upsd.users):```ini
[monuser]
password = secret
upsmon master
1. **启动NUT服务:**```bash
sudo systemctl enable nut-server nut-client
sudo systemctl start nut-server nut-client
示例用法:
- “我的所有UPS设备的状态如何?”
- “显示Dell服务器UPS的电池运行时间”
- “检查是否有电源事件”
- “获取TrippLite UPS的详细信息”
- “列出所有配置的UPS设备”
何时使用:
- 电源闪烁后 -验证UPS设备是否正确处理了事件
- 维修前 -检查电池电量和预计运行时间
- 定期监测 -跟踪UPS运行状况和电池状况
- 产能规划 -了解系统可以在电池上运行多长时间
常见UPS状态代码:
OL-在线(正常运行,交流电源存在)OB-使用电池(断电,使用电池运行)LB-电池电量低(电池电量极低,即将关机)CHRG-充电(电池正在充电)RB-更换电池(电池需要更换)
🔒 安全
自动安全检查
该项目包括自动安全验证,以防止敏感数据意外泄露:
安装预推式git挂钩(推荐):```bash
From project root
python helpers/install_git_hook.py
**它的作用:**
- 自动运行 `helpers/pre_publish_check.py` 每次git推送之前
- 包含潜在秘密或敏感数据的块推送
- 防止意外提交API密钥、密码或个人信息
**手动安全检查:**```bash
# Run security validation manually
python helpers/pre_publish_check.py
绕过安全检查(极其小心使用):```bash
Only when absolutely necessary
git push --no-verify
### 关键安全实践
**配置文件:**
- ✅ **做** 使用 `.env.example` 作为模板
- ✅ **做** 保持 `.env` 文件权限限制(`chmod 600` 在Linux/Mac上)
- ❌ **永不** 提交 `.env` 到版本控制
- ❌ **永不** 提交 `ansible_hosts.yml` 拥有真正的基础设施
- ❌ **永不** 提交 `PROJECT_INSTRUCTIONS.md` 具有真实的网络拓扑
**API安全:**
- ✅ **做** 为每个服务使用唯一的API密钥
- ✅ **做** 定期轮换API密钥(建议每90天轮换一次)
- ✅ **做** 使用强随机生成的密钥(32+个字符)
- ❌ **永不** 将Docker/Podman API暴露到互联网
- ❌ **永不** 在环境之间重用API密钥
**网络安全:**
- ✅ **做** 使用防火墙规则限制API访问
- ✅ **做** 实施VLAN分段
- ✅ **做** 尽可能启用TLS/HTTPS
- ❌ **永不** 公开管理接口
**有关详细的安全指南,请参阅 安全.md**
## 📋 需求
### 系统要求
- **python**:3.10或更高
- **克劳德桌面版**:推荐最新版本
- **网络接入**:与家庭实验室服务的连接
### Python依赖关系
通过安装 `requirements.txt`:```bash
pip install -r requirements.txt
核心依赖关系:
mcp-模型上下文协议SDKaiohttp-异步HTTP客户端pyyaml-Ansible清单的YAML解析
服务要求
- Docker/Podman:在受监视的主机上启用了API
- Pi孔:v6+已启用API
- Unifi控制器:已启用API访问
- 奥拉玛:运行API可访问的实例
- NUT(网络UPS工具):在配备UPS设备的主机上安装和配置
- 安塞波:库存文件(可选但推荐)
💻 兼容性
测试平台
在以下平台上开发和测试:
- 操作系统:Windows 11
- 克劳德桌面版:版本0.13.64
- python:版本3.13.8
跨平台注意事项
视窗:经过全面测试和支持✅
macOS:应该有效,但未经测试⚠️
Linux:应该有效,但未经测试⚠️
已知的平台差异:
- 文档中的文件路径是Windows样式的
- Unix系统可能需要调整路径分隔符
.env应在Unix上设置文件权限(chmod 600 .env)
欢迎为其他平台投稿!
🛠️ 发展
📖 第一次捐款? 阅读 CLAUDE.md 获取完整的开发指导,包括架构模式、安全要求和AI助手工作流程。
入门指南
- 安装安全git钩子(贡献者需要):```bash
python helpers/install_git_hook.py
1. **设置开发环境:**```bash
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your test values
在本地测试MCP服务器
在提交PR之前,使用MCP检查器工具在本地测试您的MCP服务器更改。
快速启动:```bash
MCP Inspector is an optional Node.js tool for interactive testing
Option 1: Use npx (no installation needed - recommended)
npx @modelcontextprotocol/inspector uv --directory . run _mcp.py
Option 2: Install globally first (one-time setup)
npm install -g @modelcontextprotocol/inspector
Then run: mcp-inspector uv --directory . run _mcp.py
这将打开一个基于web的调试器 `http://localhost:5173` 您可以在哪里:
- 查看MCP服务器的所有可用工具
- 使用示例参数测试每个工具
- 验证响应的格式是否正确
- 提交PR前调试问题
**有关详细的测试说明**,请参阅 **在本地测试MCP服务器** 部分在 贡献.md.
### 助手脚本
这 `helpers/` 目录包含用于开发和部署的实用程序脚本:
- **`install_git_hook.py`** -安装git预推钩进行自动安全检查
- **`pre_publish_check.py`** -安全验证脚本(通过git钩子自动运行)
**用途:**```bash
# Install security git hook
python helpers/install_git_hook.py
# Run security check manually
python helpers/pre_publish_check.py
项目结构```text
Homelab-MCP/
├── MCP Servers (7 production servers)
│ ├── ansible_mcp_server.py # Ansible inventory queries (integration in progress)
│ ├── docker_mcp_podman.py # Docker/Podman container monitoring
│ ├── ollama_mcp.py # Ollama AI model management
│ ├── pihole_mcp.py # Pi-hole DNS monitoring
│ ├── ping_mcp_server.py # Network connectivity testing
│ ├── unifi_mcp_optimized.py # Unifi network device monitoring
│ └── ups_mcp_server.py # UPS/NUT monitoring
│
├── Unified Server & Core Modules
│ ├── homelab_unified_mcp.py # Combines all servers (Docker entrypoint)
│ ├── mcp_config_loader.py # Secure environment variable loading
│ ├── mcp_error_handler.py # Centralized error handling
│ └── ansible_config_manager.py # Ansible inventory + enum generation
│
├── Utilities & Deprecated Tools
│ ├── unifi_exporter.py # Unifi data export utility
│ └── mcp_registry_inspector.py # MCP file management (⚠️ DEPRECATED v2.3.0)
│
├── Configuration & Examples
│ ├── .env.example # Configuration template (gitignored)
│ ├── ansible_hosts.example.yml # Ansible inventory example (gitignored)
│ ├── PROJECT_INSTRUCTIONS.example.md # AI assistant guide template
│ └── CLAUDE_CUSTOM.example.md # Local customization template (gitignored)
│
├── Documentation
│ ├── README.md # This file - user documentation
│ ├── CLAUDE.md # AI assistant development guide
│ ├── SECURITY.md # Security guidelines
│ ├── CONTRIBUTING.md # Contribution guide
│ ├── CHANGELOG.md # Version history
│ ├── MIGRATION_V3.md # Version migration guide
│ ├── CONTEXT_AWARE_SECURITY.md # Security scanning docs
│ ├── CI_CD_CHECKS.md # CI/CD automation docs
│ └── LICENSE # MIT License
│
├── Docker Deployment
│ ├── Dockerfile # Container build configuration
│ ├── docker-compose.yml # Container orchestration (uses bjeans/homelab-mcp:latest)
│ └── docker-entrypoint.sh # Container startup script
│
├── Development Tools
│ ├── helpers/
│ │ ├── install_git_hook.py # Git pre-push hook installer
│ │ ├── pre_publish_check.py # Security validation
│ │ ├── run_checks.py # CI/CD check runner
│ │ └── requirements-dev.txt # Development dependencies
│ ├── requirements.txt # Production Python dependencies
│ └── .gitignore # Git ignore rules
### 添加新的MCP服务器
1. **创建服务器文件**```python
#!/usr/bin/env python3
"""
My Service MCP Server
Description of what it does
"""
import asyncio
from mcp.server import Server
# ... implement tools ...
- 将配置添加到
.env.example```bash
My Service Configuration
MY_SERVICE_HOST=192.168.1.100
MY_SERVICE_API_KEY=your-api-key
1. **更新文档**
- 将服务器详细信息添加到此README中
- 更新 `PROJECT_INSTRUCTIONS.example.md`
- 更新 `CLAUDE.md` 如果添加新的模式或功能
- 如果适用,添加安全说明
1. **彻底测试**
- 使用真实基础设施进行测试
- 验证错误处理
- 检查是否存在敏感数据泄漏
- 审查安全影响
### 环境变量
所有MCP服务器都支持两种配置方法:
**1.环境变量(`.env` 文件)**
- 简单键=值对
- 由每个MCP服务器自动加载
- 适用于简单的设置或测试
**2.可靠库存(建议生产)**
- 集中式基础设施定义
- 支持复杂的主机分组
- 更适合多主机环境
- 集 `ANSIBLE_INVENTORY_PATH` 在 `.env`
### 编码标准
- **Python 3.10+** 语法和特征
- **异步/等待** 用于所有I/O操作
- **类型提示** 在有益的地方
- **错误处理** 用于网络操作
- **日志记录** 转到stderr进行调试
- **安全**:验证输入,净化输出
### 测试检查表
在提交更改之前:
- \[\]已安装安全git挂钩(`python helpers/install_git_hook.py`)
- \[\]手动安全检查通过(`python helpers/pre_publish_check.py`)
- \[\]代码或提交中没有敏感数据
- \[\]所有配置的环境变量
- \[\]网络故障的错误处理
- \[\]日志记录不会泄露秘密
- \[\]文件已更新
- \[\]审查了安全影响
- \[ \] `.gitignore` 必要时更新
## 🐛 故障排除
### MCP服务器未出现在Claude中
1. **检查Claude桌面配置:**```bash
# Windows
type %APPDATA%\Claude\claude_desktop_config.json
# Mac/Linux
cat ~/.config/Claude/claude_desktop_config.json
-
验证Python路径是否正确 在配置中
-
重新启动克劳德桌面 完全
-
检查日志 -MCP服务器登录到stderr
连接错误
Docker/Podman API:```bash
Test connectivity
curl http://your-host:2375/containers/json
Check firewall
netstat -an | grep 2375
**Pi-hole API:**```bash
# Test API key
curl "http://your-pihole/api/stats/summary?sid=YOUR_API_KEY"
奥拉马:```bash
Test Ollama endpoint
curl http://your-host:11434/api/tags
### 理解错误消息
**错误消息格式(v2.2.0+):**
所有MCP服务器现在都以以下格式提供详细的、可操作的错误消息:```
✗ [Service] [Error Type] (HTTP Status)
[Specific problem description]
Host: [hostname:port]
→ [Actionable remediation steps]
Technical details: [error details] (timestamp)
常见错误类型:
1.身份验证失败(401)
例子:```
✗ Pi-hole Authentication Failed (401)
Invalid API key for pi-hole-1
Host: 192.168.1.5:80
→ Verify PIHOLE_API_KEY_PI_HOLE_1 in .env matches your Pi-hole admin password.
→ You can find/reset this in Pi-hole Settings > API.
**如何修复:**
1. 检查你的 `.env` 正确的API密钥变量的文件
1. 验证API密钥是否与服务的管理面板匹配
1. 对于Pi-hole:设置>API>显示API令牌
1. 对于Unifi:设置>管理员>API>生成密钥
#### 2.连接失败
**例子:**```
✗ Unifi Connection Failed
Unable to connect to unifi-controller:443
Host: unifi-controller:443
→ Ensure Unifi controller is running and accessible at unifi-controller:443.
→ Test connectivity: nc -zv unifi-controller 443
→ Check firewall: sudo iptables -L | grep 443
如何修复:
- 验证服务是否正在运行:
systemctl status [service-name] - 测试网络连接
nc或telnet - 检查防火墙规则是否允许访问端口
- 验证配置中的主机名/IP是否正确
3.超时错误
例子:```
✗ Ollama Timeout
Connection to ollama-1:11434 timed out (after 5s)
Host: ollama-1:11434
→ The service is not responding. Check if Ollama is running and not overloaded.
→ Check service status and logs for performance issues.
```
…(正文过长,页面只展示前面部分,完整内容见仓库)
