AI导哈

AI助手基础设施管理工具

mcp-homelab是一个为AI助手提供实时访问家庭实验室基础设施的服务器，支持通过自然语言查询节点状态、管理Docker容器、控制Proxmox虚拟机及检查OPNsense防火墙状态。

  • by asvarnon
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 asvarnon/mcp-homelab

使用说明

mcp家庭实验室

一 主控程序 服务器，让AI助手实时访问您的家庭实验室基础设施。将其连接到Claude Desktop、VS Code Copilot或任何兼容MCP的客户端，您的助手可以通过自然对话查询节点状态、管理Docker容器、控制Proxmox VM和检查OPNsense防火墙状态。

为什么

人工智能助手对基础设施工作很有用，但他们看不到你的环境。你最终会复制粘贴 docker ps 输出，描述您的网络布局，并手动馈送上下文。mcp-homelab通过让助手通过SSH和REST API直接访问实时基础设施数据来修复这个问题。

它支持什么：

  • 任何Linux主机 可通过SSH访问（裸机、VM、LXC容器）
  • 码头工人 容器列表、日志和重启
  • Proxmox VE VM和LXC容器管理（可选）
  • OPNsense 防火墙检查（可选）

Proxmox和OPNsense是可选的——服务器只适用于SSH可访问的主机。

需求

  • Python 3.10+
  • SSH密钥访问 至少连接到一个Linux主机
  • MCP客户端：Claude Desktop、带Copilot的VS Code或任何兼容MCP的客户端
  • （可选） 带有API令牌的Proxmox VE
  • （可选） 带API密钥/机密的OPNsense

快速开始

git clone git@github.com:asvarnon/mcp-homelab.git
cd mcp-homelab
python -m venv .venv && .venv/Scripts/activate  # or source .venv/bin/activate on Linux/macOS
pip install -e .
mcp-homelab init                # creates config.yaml + .env from templates
# Edit config.yaml with your hosts, .env with API credentials
mcp-homelab setup check         # validates config and tests connectivity
mcp-homelab setup client        # auto-configures Claude Desktop / VS Code

就是这样。您的MCP客户端现在将在需要家庭实验室数据时自动生成服务器。

工具

类别 工具 描述
发现 scan_infrastructure 完整拓扑快照（所有节点、VM、容器、接口）
发现 generate_context 从实时扫描数据自动生成Markdown文档
发现 list_context_files 上下文目录中所有文件的清单
节点 list_nodes 配置中的所有已配置节点
节点 get_node_status 正常运行时间、CPU、RAM、通过SSH连接的磁盘
节点 list_containers 节点上的Docker容器
节点 get_container_logs 容器日志的最后N行
节点 restart_container 重新启动容器
Proxmox list_vms 所有具有状态和资源的虚拟机
Proxmox get_vm_status 一个虚拟机的详细状态
Proxmox start_vm 启动已停止的VM
Proxmox stop_vm 优雅地停止虚拟机
Proxmox list_lxc 所有具有状态和资源的LXC容器
Proxmox get_lxc_status 一个LXC容器的详细状态
Proxmox start_lxc 启动已停止的LXC容器
Proxmox stop_lxc 优雅地停止LXC容器
Proxmox create_lxc 从模板创建新的LXC容器
Proxmox get_next_vmid 集群中的下一个可用VM/CT ID
Proxmox list_storage 带有容量信息的存储池
Proxmox list_templates 用于创建LXC的可用操作系统模板
OPNsense get_dhcp_leases 活动DHCP租约
OPNsense get_interface_status 接口状态
OPNsense get_firewall_aliases 别名定义

详细设置

上面的快速入门涵盖了基础知识。本节详细介绍了具体的集成。

配置

cp config.yaml.example config.yaml
cp .env.example .env
# Edit config.yaml with your hosts, then .env with API credentials

Proxmox API令牌（可选）

在Proxmox web用户界面中(https://your-pve-host:8006):

  1. 数据中心→ 权限→ API令牌→ Add
  2. 用户： 您的PVE用户（例如。 admin@pam)
  3. 令牌ID: mcp-homelab （或任何标签）
  4. 特权分离： 取消选中（令牌继承用户权限）
  5. 复制令牌密钥——它只显示一次

添加 .env:

PROXMOX_TOKEN_ID=admin@pam!mcp-homelab
PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Proxmox主机/端口/SSL设置位于 config.yaml 在...之下 proxmox: 部分。您还可以配置LXC创建默认值：

proxmox:
  host: "10.10.10.50"
  port: 8006
  verify_ssl: false
  default_node: pve           # preferred node for storage/template queries
  default_storage: local      # rootfs storage for create_lxc ("local" = dir, "local-lvm" = LVM thin)
  default_bridge: vmbr0       # network bridge for create_lxc

节点接入

每个节点的SSH凭据在中定义 config.yaml （每个节点 ssh_user 和 ssh_key_path 字段）。编辑这些以匹配您的环境。

Docker sudo（如果需要）

如果SSH用户是 不 在 docker 组，组 sudo_docker: true 对于该节点 config.yaml。这需要 无密码sudo 对于目标主机上的docker二进制文件：

# On the remote node:
echo '<username> ALL=(ALL) NOPASSWD: /usr/bin/docker' | sudo tee /etc/sudoers.d/docker-nopasswd
sudo chmod 440 /etc/sudoers.d/docker-nopasswd
sudo visudo -cf /etc/sudoers.d/docker-nopasswd   # must print "parsed OK"

如果SSH用户已经在 docker 组，组 sudo_docker: false （默认设置），不需要突然更改。

常见陷阱： 不要将sudoers规则限制为特定的docker子命令（例如。 /usr/bin/docker ps, /usr/bin/docker exec *).Sudoers将参数视为完全匹配-- docker ps 不匹配 docker ps --format '{{json .}}'，这就是MCP工具实际运行的内容。使用 /usr/bin/docker （仅二进制路径，没有子命令）允许所有带有任何参数的docker操作。

硬件内存详细信息（可选）

generate_context 和 scan_infrastructure 通过SSH收集硬件规格。大多数数据来自无特权命令(lscpu, /proc/meminfo, lsblk)但是 每个DIMM内存的详细信息 （类型、速度、制造商）要求 dmidecode，这需要root访问权限。

如果您想在生成的文档中查看内存模块的详细信息，请为dmidecode授予无密码sudo：

# On each remote node:
echo '<username> ALL=(ALL) NOPASSWD: /usr/sbin/dmidecode' | sudo tee /etc/sudoers.d/dmidecode-nopasswd
sudo chmod 440 /etc/sudoers.d/dmidecode-nopasswd
sudo visudo -cf /etc/sudoers.d/dmidecode-nopasswd   # must print "parsed OK"

如果没有这个，其他一切仍然可以工作——内存模块部分只是从生成的文档中省略了。

组合式sudoers文件（推荐）

对于需要两者的节点 sudo_docker: true 以及硬件内存详细信息，您可以将这两个规则合并到一个文件中：

# On the remote node:
cat <<EOF | sudo tee /etc/sudoers.d/mcp-homelab
<username> ALL=(root) NOPASSWD: /usr/bin/docker, /usr/sbin/dmidecode
EOF
sudo chmod 440 /etc/sudoers.d/mcp-homelab
sudo visudo -cf /etc/sudoers.d/mcp-homelab   # must print "parsed OK"

MCP客户端连接

这 setup client 命令自动配置Claude Desktop和VS Code以使用您的服务器。它检测您的venv Python，解析路径，并将条目合并到现有的配置文件中，而不会覆盖其他服务器。

# Interactive — picks Claude Desktop, VS Code, or both
mcp-homelab setup client

# Preview what would be written (no changes)
mcp-homelab setup client --dry-run

这将写入正确的stdio传输条目，包括 MCP_HOMELAB_CONFIG_DIR env-var，这样服务器就可以找到 config.yaml 和 .env 而不管客户端的工作目录如何。

Manual configuration (if you prefer editing JSON directly)

克劳德桌面 --编辑 %APPDATA%/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "homelab": {
      "command": "C:/path/to/mcp-homelab/.venv/Scripts/python.exe",
      "args": ["C:/path/to/mcp-homelab/server.py"],
      "env": {
        "MCP_HOMELAB_CONFIG_DIR": "C:/path/to/mcp-homelab"
      }
    }
  }
}

VS代码（副本） --添加 .vscode/mcp.json 在您的工作空间中：

{
  "servers": {
    "homelab": {
      "command": "C:/path/to/mcp-homelab/.venv/Scripts/python.exe",
      "args": ["C:/path/to/mcp-homelab/server.py"],
      "env": {
        "MCP_HOMELAB_CONFIG_DIR": "C:/path/to/mcp-homelab"
      }
    }
  }
}

这 MCP_HOMELAB_CONFIG_DIR env-var是必需的——没有它，从不同工作目录生成的MCP客户端将无法找到您的配置文件。

OAuth客户端锁定（托管模式）

在HTTP模式下运行时，mcp-homelab使用OAuth 2.1进行身份验证。默认情况下，它接受来自任何客户端的动态客户端注册（DCR）。要限制对单个预注册客户端的访问，请在 .env:

# Generate credentials (both must be ≥32 characters)
python -c "import secrets; print(secrets.token_urlsafe(48))"

# Add to .env
MCP_CLIENT_ID=<generated-value>
MCP_CLIENT_SECRET=<generated-value>

当两者都设置好时，此静态客户端将与动态客户端注册（DCR）一起预先注册。要限制哪些客户端可以动态注册，请设置 MCP_ALLOWED_REDIRECT_ORIGINS （逗号分隔的起源）。从Claude Desktop连接时，在OAuth客户端ID/客户端密码提示中输入这些值。

如果两者都没有设置，服务器将使用开放的DCR（向后兼容，适用于受信任的局域网）。

托管模式（多客户端）

想将mcp-homelab作为可从多台机器、Claude.ai或移动设备访问的共享服务运行吗？请参阅 托管模式指南 适用于整个工作流程，包括特定于平台的工作流程 Proxmox LXC+Cloudflare隧道 参考架构。

直接运行

python server.py

服务器在stdio传输（MCP的标准）上启动。通常你不会直接运行它——MCP客户端会自动生成它。

自定义上下文注释

mcp homelab将基础设施文档生成到 context/generated/ 来自实时扫描数据。如果你也有自己策划的笔记（架构文档、运行手册等），你想让你的人工智能助手参考， 不要把它们放在这个项目中.

相反，请将文档工作区直接连接到MCP客户端：

  • 克劳德桌面/聊天GPT： 添加一个指向您的文档文件夹的单独文件系统MCP服务器
  • VS代码/副本： 将您的文档文件夹添加到工作区——代理会自动查看所有工作区文件

这使得关注点保持分离：mcp homelab处理实时基础设施状态，您的文档工作区处理策划的知识，mcp客户端聚合这两者。

测试

单元测试使用带有完整模拟的pytest——不需要真正的基础设施。

安装测试依赖项

pip install pytest pytest-asyncio

运行测试

# All tests
python -m pytest tests/ -v

# Single module
python -m pytest tests/unit/test_node_parsers.py -v

# Single test class
python -m pytest tests/unit/test_ssh.py::TestConnect -v

# Single test
python -m pytest tests/unit/test_config.py::TestBootstrapConfigDir::test_sets_env_when_unset -v

测试结构

tests/
├── conftest.py                  # Shared fixtures (sample configs, mock SSH, env helpers)
└── unit/
    ├── test_config.py           # Config loading, bootstrap, env validation, Pydantic models
    ├── test_ssh.py              # Connection caching, stale eviction, credential resolution
    ├── test_node_parsers.py     # All SSH output parsers (uptime, CPU, memory, disk, Docker,
    │                            #   lscpu, meminfo, lsblk, dmidecode, labels, rounding)
    ├── test_proxmox_tools.py    # VM/LXC tools, storage, templates, node discovery, input validation
    ├── test_opnsense_tools.py   # DHCP leases, interfaces, firewall aliases
    ├── test_prompts.py          # Input validation (IP, int, path, yes/no, node names)
    ├── test_config_writer.py    # YAML round-trip, .env upserts, section preservation
    └── test_client_setup.py     # JSONC stripping, OS detection, atomic writes, config merging

项目结构

mcp-homelab/
├── server.py              # MCP entry point — registers all tools
├── tools/
│   ├── discovery.py       # Composite scan tool for agent bootstrapping
│   ├── context_gen.py     # Documentation generation from scan data
│   ├── nodes.py           # SSH-based node tools + output parsers
│   ├── proxmox.py         # Proxmox REST API tools
│   └── opnsense.py        # OPNsense REST API tools
├── core/
│   ├── config.py          # Config loader, bootstrap, env var accessors
│   ├── ssh.py             # SSH connection manager (paramiko)
│   ├── proxmox_api.py     # Proxmox REST API client (httpx)
│   └── opnsense_api.py    # OPNsense REST API client (httpx)
├── mcp_homelab/
│   ├── cli.py             # CLI entry point (init, serve, setup)
│   └── setup/
│       ├── prompts.py     # Validated input prompts
│       ├── config_writer.py # YAML/env round-trip writer
│       ├── node_setup.py  # Interactive node configuration
│       ├── client_setup.py # MCP client config writer (Claude Desktop, VS Code)
│       ├── check.py       # Read-only health check
│       └── ssh_helpers.py # SSH test + capability detection
├── tests/                 # pytest unit tests (see Testing section)
├── config.yaml.example    # Example host definitions (copy to config.yaml)
├── .env.example           # Required env vars template
├── requirements.txt       # Runtime dependencies
├── pyproject.toml         # Package metadata + pytest config
└── Dockerfile             # Container packaging

未来更新

  • Dockerfile打包 --当前的Dockerfile是一个存根；需要stdio传输的设计工作
  • FreeBSD内存精度 --BSD内存报告可以包括非活动/缓存页面，以获得更精确的已用内存值
  • 配置验证警告 --检测可能的错误配置（例如。， sudo_docker 没有 docker)启动时

相关 MCP