Homelab MCP

MCPAI代理

提供方 bjeans

AI代理 stdio · 本地进程 API Key 社区 / 第三方 Claude DesktopClaude
查看接入方式

Homelab MCP Servers是一个通过Claude Desktop管理和监控家庭实验室基础设施的模型上下文协议(MCP)服务器集合。

一句话选型结论

按资料字段整理

Homelab MCP 属于AI代理类 MCP 服务器,stdio · 本地进程,API Key,可直接接入 Claude Desktop、Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式stdio · 本地进程 鉴权API Key 部署方式本地部署
GitHub 星标 27 仓库热度,无公开仓库时显示未标注
工具数 29 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量29暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

家庭实验室Python本地部署基础设施管理MCP协议Docker管理网络监控

安装与配置

stdio · 本地进程 API Key
客户端在本机拉起子进程,数据不出本机
pip install -r requirements.txt

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 29 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 29 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Homelab MCP当前 29 stdio · 本地进程 本地部署 有 2026-05-17
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方bjeans上游标注的维护方 bjeans
分类AI代理本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

48.2 KB
来自项目仓库与上游目录的原文,未做删改

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服务器之后, 创建个性化的项目说明:

  1. 复制示例模板:```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.0 Git发布
  • 在那之前,使用 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实例:

  1. 安装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
  1. 启动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
  1. 配置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
  1. 配置访问权限(/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 -模型上下文协议SDK
  • aiohttp -异步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助手工作流程。

入门指南

  1. 安装安全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 ...
  1. 将配置添加到 .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
  1. 验证Python路径是否正确 在配置中

  2. 重新启动克劳德桌面 完全

  3. 检查日志 -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

如何修复:

  1. 验证服务是否正在运行: systemctl status [service-name]
  2. 测试网络连接 nc 或 telnet
  3. 检查防火墙规则是否允许访问端口
  4. 验证配置中的主机名/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.
```

…(正文过长,页面只展示前面部分,完整内容见仓库)

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Homelab MCP 怎么安装?

在客户端按下面的安装命令接入:pip install -r requirements.txt。装完在客户端配置里引用同一个包或端点。

Homelab MCP 怎么在 Claude Desktop、Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Homelab MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Homelab MCP 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

Homelab MCP 支持哪些客户端?

资料标注支持 Claude Desktop、Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Homelab MCP 能提供哪些能力?

资料显示约 29 个工具;能力标签包括 基础设施管理、Python、Claude、网络监控。具体工具清单以官方文档为准。

Homelab MCP 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

Homelab MCP 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。