Homelab MCP 服务器

Python 3.12+ License: MIT

通过模型上下文协议 (MCP) 实现 AI 驱动的家庭实验室基础设施管理

一个 Python MCP 服务器，使 AI 助手能够管理、部署和监控家庭实验室基础设施。工具涵盖 SSH 发现、虚拟机管理、服务安装、网络拓扑映射、Proxmox 操作和凭据管理。

主要功能

SSH 发现 -- 从任何系统收集全面的硬件和软件信息
服务安装 -- 从模板部署 Jellyfin、Pi-hole、Ollama、Home Assistant 等
Proxmox 集成 -- 完全 API 访问权限以及社区脚本发现
虚拟机/容器生命周期 -- 部署、控制和移除 Docker 和 LXD 工作负载
网络映射 -- 发现设备、分析拓扑并跟踪更改
Terraform 和 Ansible -- 具有漂移检测和剧本的状态管理部署
凭据管理 -- 注册一次服务器，无需重新输入凭据即可连接

快速入门

# Install from PyPI (recommended — no clone needed)
uvx homelab-mcp

# Or clone and run from source
git clone https://github.com/washyu/homelab_mcp.git
cd homelab_mcp
uv sync && uv run python run_server.py

有关完整演练（环境变量、MCP 客户端配置、首次工具调用），请参阅设置指南。

文档

指南	描述
设置指南	从零到首次工具调用
工具参考	所有带有参数和示例的工具
配置	环境变量和 CLI 选项
Claude Desktop 设置	Claude Desktop 集成指南

工作原理

设置 -- 服务器在首次运行时生成 SSH 密钥对 (~/.ssh/mcp_admin_rsa)
接入主机 -- 使用 setup_mcp_admin 在目标系统上创建受管用户
验证 -- 使用 verify_mcp_admin 确认无密码 SSH 访问
管理 -- 发现硬件、安装服务、控制虚拟机并映射您的网络

服务器通过 stdio 使用 MCP 协议进行通信。将其连接到任何兼容 MCP 的客户端（Claude Desktop 等），并通过自然语言进行交互。

凭据管理

存储一次 SSH 和 Proxmox 凭据，以便服务器在每次连接时自动注入它们：

# Store an SSH credential
homelab-mcp credentials add 192.168.1.10 admin

# Store a Proxmox API credential
homelab-mcp credentials add 192.168.1.200 root@pam --type proxmox

# List stored credentials
homelab-mcp credentials list
homelab-mcp credentials list --type proxmox

# Remove a credential
homelab-mcp credentials remove 192.168.1.10

凭据存储在操作系统密钥环中（Linux 上为 libsecret，macOS 上为 Keychain）。当操作系统密钥环不可用（无头服务器）时，凭据将回退到环境变量。

有关完整文档，请参阅凭据 CLI 参考。

MCP 客户端配置

通过 PyPI (uvx) — 推荐：

{
  "mcpServers": {
    "homelab": {
      "command": "uvx",
      "args": ["homelab-mcp"]
    }
  }
}

通过源码克隆：

{
  "mcpServers": {
    "homelab": {
      "command": "uv",
      "args": ["run", "python", "run_server.py"],
      "cwd": "/path/to/homelab_mcp"
    }
  }
}

开发

# Install with dev dependencies
uv sync --group dev

# Run tests (unit only, no Docker required)
uv run pytest tests/ -m "not integration"

# Code quality
uv run ruff check src/ tests/
uv run mypy src/

有关生产部署的详细信息，请参阅 DEPLOYMENT.md。

项目结构

src/homelab_mcp/
  server.py              # MCP server with JSON-RPC protocol
  tool_schemas/          # Tool definitions (8 schema files)
  tool_annotations.py    # MCP annotation hints per tool
  ssh_tools.py           # SSH discovery and hardware detection
  service_installer.py   # Service installation framework
  infrastructure_crud.py # Infrastructure lifecycle management
  vm_operations.py       # VM/container operations
  sitemap.py             # Network topology mapping
  database.py            # SQLite device tracking
  error_handling.py      # Centralized error handling
  credential_store.py    # OS keyring credential storage
  log_filter.py          # Credential redaction for log output
  prompt_registry.py     # MCP prompts registry
  resource_readers.py    # MCP resource read handlers
  service_templates/     # YAML service definitions
tests/                   # Unit and integration tests
docs/                    # Full documentation

致谢

Proxmox 社区脚本集成由 community-scripts/ProxmoxVE (MIT 许可证) 提供支持。

贡献

Fork 本仓库
创建功能分支
为新功能编写测试
确保所有测试通过
提交拉取请求

许可证

MIT 许可证 -- 详情请参阅 LICENSE 文件。

Homelab MCP Server

Homelab MCP 服务器

主要功能

快速入门

文档

工作原理

凭据管理

MCP 客户端配置

开发

项目结构

致谢

贡献

许可证

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API