Homelab MCP 服务器集合

使用背景

• 该仓库实现了若干 MCP 服务器实例和一个统一入口，提供对资源、工具、Prompts 的管理与执行能力，并通过 JSON-RPC 的 MCP 协议与客户端通信。通过不同模块可对 Docker/Podman、Pihole、Unifi、Ollama、Pi-hole、UPS、Ping、Ansible 等进行对接与调用，便于 LLM 在对运维、监控、自动化任务中的上下文服务接入。

主要功能点

• 授权与配置加载：通过 mcp_config_loader.py 提供安全的环境变量加载和启用清单，支持 .env 加载、按模式允许变量等。
• 资源与工具暴露：各 MCP 子服务器（如 docker_mcp_podman.py、pihole_mcp.py、ollama_mcp.py、ping_mcp_server.py、unifi_mcp_optimized.py、ups_mcp_server.py、ansible_mcp_server.py 等）实现资源/工具的列出与执行。
• JSON-RPC 服务：通过 @server.list_tools() 和 @server.call_tool() 等装饰器，向客户端暴露工具清单和工具执行入口，遵循 MCP 的请求/响应模式。
• 统一入口（可选）：homelab_unified_mcp.py 及其 UnifiedHomelabServer 将各子服务器的工具聚合为一个入口，便于单点对接。
• 会话与安全：对环境变量的严格化加载、统一的统一模式（MCP_UNIFIED_MODE）以避免重复加载，提供对敏感信息的防护策略。
• 多传输与会话：代码中采用 stdio（stdio_server）作为传输实现，理论上也支持其他传输模式（SSE、WebSocket 等），以实现对 LLM 的安全、可扩展的上下文服务。

安装与运行步骤

• 安装依赖与准备环境
  • 运行需要 Python 3.x 环境，安装仓库所依赖的 Python 包（如 aiohttp、PyYAML、ansible 及其他运行时依赖）。具体依赖请参考各模块的实际需求。
• 启动入口
  • 如果需要统一入口，请运行统一入口文件以启动 Unified Homelab MCP 服务器。
    • python homelab_unified_mcp.py
  • 若单独运行某个子服务器，请启动对应的入口脚本，例如 ollama_mcp.py、pihole_mcp.py 等。
• MCP 客户端连接配置（示例，供客户端参考）
  • 服务器配置示例（JSON，描述 MCP 客户端如何连接 MCP 服务器）： { "server_name": "homelab-unified", "command": "python", "args": ["homelab_unified_mcp.py"] }
  • 说明：
    • server_name：MCP 服务器在客户端侧的标识名称，应与实际启动的服务器名称一致。
    • command：启动 MCP 服务器所用的命令，通常为 python。
    • args：启动命令的参数，指向启动入口脚本，如 homelab_unified_mcp.py。
    • 客户端不需要对服务器内部实现细节（如具体子服务器、读环境变量的细节）做额外配置，只需要知道启动入口以及如何通过 MCP 协议与其交互。
• 运行与调试
  • 启动后，客户端通过 MCP 协议即可请求以下能力：列出工具、执行工具、获取资源、渲染 Prompts 等等。具体工具名称和输入输出格式请参阅各服务器实现中的 Tool 定义。
  • 如遇到环境变量、inventory、或外部服务接入问题，请按照各子服务器的日志输出进行排查。

基本使用方法（简要示例）

• 获取可用工具列表：请求服务器的 list_tools 接口，得到该 MCP 服务器暴露的工具集合。
• 调用工具：通过 call_tool 接口，指定工具名称及参数，获取返回的文本内容或结构化数据。
• 组合使用：将多个子服务器的工具在同一个 MCP 客户端工作流中串联，通过返回的文本信息进行下一步推理和决策。
• 统一入口优点：通过 UnifiedHomelabServer，可以一次性访问 docker、ping、ollama、pihole、unifi 等分组工具，便于对整个本地网络环境进行统一的对话式管理。