Homelab MCP

Homelab MCP是一個用於通過Claude Desktop管理和監控家庭實驗室基礎設施的Model Context Protocol服務器集合，支持Docker、Ollama、Pi-hole、Unifi、UPS等多種服務，提供統一和獨立兩種部署模式。

家庭自動化與物聯網監控 #家庭實驗室 #基礎設施管理 #MCP協議 #監控工具 .Python

評分 : 2.5分

下載量 : 5.9K

更新時間 : 2025-12-12

打開站點

安裝

複製以下命令到你的Client進行配置

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

{
  "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"]
    }
  }
}

{
  "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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

{
  "mcpServers": {
    "homelab-unified": {
      "command": "docker",
      "args": ["exec", "-i", "homelab-mcp", "python", "homelab_unified_mcp.py"]
    }
  }
}

{
  "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"]
    }
  }
}

注意：您的密鑰屬於敏感信息，請勿與任何人分享。

🚀 家用實驗室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

請記住：本項目涉及關鍵基礎設施。請始終優先考慮安全，並先在安全的環境中測試更改！

Markdownify MCP

Markdownify是一個多功能文件轉換服務，支持將PDF、圖片、音頻等多種格式及網頁內容轉換為Markdown格式。

百度地圖MCP Server是國內首個兼容MCP協議的地圖服務，提供地理編碼、路線規劃等10個標準化API接口，支持Python和Typescript快速接入，賦能智能體實現地圖相關功能。

Firecrawl MCP Server是一個集成Firecrawl網頁抓取能力的模型上下文協議服務器，提供豐富的網頁抓取、搜索和內容提取功能。

TypeScript

85.2K

5分

Sequential Thinking MCP Server

一個基於MCP協議的結構化思維服務器，通過定義思考階段幫助分解複雜問題並生成總結

一個基於Python的MCP服務器，通過Notion API提供高級待辦事項管理和內容組織功能，實現AI模型與Notion的無縫集成。

Magic Component Platform (MCP) 是一個AI驅動的UI組件生成工具，通過自然語言描述幫助開發者快速創建現代化UI組件，支持多種IDE集成。

JavaScript

16.2K

5分

Edgeone Pages MCP Server

EdgeOne Pages MCP是一個通過MCP協議快速部署HTML內容到EdgeOne Pages並獲取公開URL的服務

Context7 MCP是一個為AI編程助手提供即時、版本特定文檔和代碼示例的服務，通過Model Context Protocol直接集成到提示中，解決LLM使用過時信息的問題。

智啟未來，您的人工智慧解決方案智庫

Homelab MCP

安裝

內容詳情

替代品

安裝

🚀 家用實驗室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助手和開發者

貢獻者快速開始

拉取請求流程

代碼審查標準

🙏 致謝

📞 支持

替代品