AI导哈

远程MCP服务器

Homelab MCP Server是一款用于管理家庭实验室基础设施的远程MCP服务器，提供监控和管理Docker容器、OPNsense防火墙、TrueNAS存储、Proxmox虚拟化和Home Assistant服务状态的功能。

  • by bshandley
  • TypeScript
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 bshandley/homelab-mcp

使用说明

Homelab MCP服务器

用于管理家庭实验室基础设施的远程MCP（模型上下文协议）服务器。为Claude提供监控和管理Docker容器、OPNsense防火墙、TrueNAS存储、Proxmox虚拟化和家庭助理服务状态的工具。

特性

  • 4能力等级：从只读监控到完全管理控制
  • Docker管理：列出、监控、控制集装箱和码头堆栈
  • OPNsense集成：监视防火墙状态并重新启动服务
  • TrueNAS集成：检查池运行状况、管理数据集、创建快照
  • Proxmox集成：监控和管理虚拟机/容器，创建快照
  • 家庭助理集成：监视服务运行状况、实体状态、配置和错误日志
  • 系统监控：主机上的CPU、内存、磁盘使用情况

⚠️ 危险-先读这个

该软件允许AI模型直接控制您的网络基础设施。请务必谨慎使用。

关键风险

  • AI可能会犯错：语言模型可能会误解指令、产生幻觉需求或执行意外操作。像“清理未使用的容器”这样的简单请求可能会导致关键服务停止。

  • 破坏性行动是可能的：在更高的能力级别（3-4），人工智能可以：

    • 删除虚拟机和容器
    • 修改网络配置
    • 删除关键数据集或快照
    • 在生产系统中执行任意命令
    • 覆盖docker组合文件，可能导致数据丢失

  • 无撤消按钮：一旦AI执行了破坏性操作（删除VM、删除数据集、停止关键服务），损害是即时的，可能是不可逆转的。

  • 网络安全影响：此服务器提供对防火墙、存储系统和虚拟化平台的API访问。泄露的API密钥或错误配置的功能级别可能允许对整个homeab进行未经授权的控制。

  • 误解时有发生：人工智能模型可能无法完全理解基础设施的依赖关系。重新启动一项服务可能会导致网络范围内的中断。

建议

  1. 从1级开始（只读）：始终从只监控访问开始，只有在绝对必要时才提高能力水平。

  2. 开发中的测试：如果可能的话，首先使用非生产基础设施进行测试，以了解AI如何解释您的请求。

  3. 执行前审查：在2+级，在确认执行之前，仔细审查人工智能计划采取的行动。

  4. 保留备份：在授予3+级访问权限之前，请确保您拥有所有关键系统的最新备份。

  5. 旋转凭据：定期轮换API密钥和OAuth凭据。把它们当作高度敏感的。

  6. 监控日志：查看容器日志，查看实时执行的操作。

  7. 使用网络分段：考虑在对关键基础设施访问受限的受限网段中运行此服务器。

通过使用此软件，您承认您了解这些风险，并对AI采取的任何行动承担全部责任，包括数据丢失、服务中断或安全事件。

快速开始

1.先决条件

  • 目标主机（Wharf）上安装了Docker和Docker Compose
  • OPNsense API凭据（可选）
  • TrueNAS API密钥（可选）
  • Node.js 20+（用于本地开发）

2.设置

# Clone or copy the project to your host
cd homelab-mcp

# Copy example environment file
cp .env.example .env

# Generate a secure API key
openssl rand -hex 32

# Edit .env and add your credentials
nano .env

3.配置

编辑 .env 使用您的设置：

CAPABILITY_LEVEL=1        # Start with level 1 (read-only)
API_KEY=your-api-key-here # Use the generated key
PORT=3005

# OPNsense (optional)
OPNSENSE_HOST=10.0.0.1
OPNSENSE_API_KEY=your-key
OPNSENSE_API_SECRET=your-secret

# TrueNAS (optional)
TRUENAS_HOST=10.0.0.105
TRUENAS_API_KEY=your-key

# Proxmox (optional)
PROXMOX_HOST=10.0.0.2
PROXMOX_TOKEN_ID=root@pam!mytoken
PROXMOX_TOKEN_SECRET=your-secret

# Home Assistant (optional)
HOME_ASSISTANT_HOST=10.0.0.103
HOME_ASSISTANT_PORT=8123
HOME_ASSISTANT_TOKEN=your-long-lived-token
HOME_ASSISTANT_USE_HTTPS=false

4.构建和部署

# Build TypeScript
npm install
npm run build

# Build Docker image
docker compose build

# Start the server
docker compose up -d

# Check logs
docker compose logs -f

5.配置克劳德桌面

添加到您的Claude Desktop MCP设置中：

{
  "mcpServers": {
    "homelab": {
      "command": "node",
      "args": ["/path/to/homelab-mcp/dist/index.js"],
      "env": {
        "CAPABILITY_LEVEL": "1",
        "API_KEY": "your-api-key-here",
        "OPNSENSE_HOST": "10.0.0.1",
        "OPNSENSE_API_KEY": "your-key",
        "OPNSENSE_API_SECRET": "your-secret",
        "TRUENAS_HOST": "10.0.0.105",
        "TRUENAS_API_KEY": "your-key",
        "PROXMOX_HOST": "10.0.0.2",
        "PROXMOX_TOKEN_ID": "root@pam!mytoken",
        "PROXMOX_TOKEN_SECRET": "your-secret",
        "HOME_ASSISTANT_HOST": "10.0.0.103",
        "HOME_ASSISTANT_PORT": "8123",
        "HOME_ASSISTANT_TOKEN": "your-long-lived-token",
        "HOME_ASSISTANT_USE_HTTPS": "false"
      }
    }
  }
}

远程访问（克劳德聊天）

要从Claude Chat（web界面）访问MCP服务器，请使用HTTP传输进行部署：

  1. 在中设置环境变量 .env:

    PORT=3000
API_KEY=your-generated-key
CAPABILITY_LEVEL=1

  2. 部署容器：

    docker compose up -d

  3. 配置反向代理 （例如，Traefik、Pangolin、nginx）路由 mcp.example.com 到 http://localhost:3000

  4. 添加DNS记录 指向 mcp.example.com 到您的服务器

  5. 在克劳德聊天，添加MCP服务器：

    • 网址： https://mcp.example.com/mcp
    • 身份验证：承载令牌
    • 令牌：您的API_KEY值

OAuth 2.0身份验证（适用于Claude Chat）

Claude Chat要求OAuth 2.0用于自定义连接器。此服务器支持客户端凭据流。

  1. 生成OAuth凭据：

    # Generate client ID
openssl rand -hex 32

# Generate client secret
openssl rand -hex 32

  2. 添加 .env:

    OAUTH_CLIENT_ID=your-generated-client-id
OAUTH_CLIENT_SECRET=your-generated-client-secret

  3. 在Claude Chat中，添加连接器：

    • 姓名： Homelab
    • 远程MCP服务器URL: https://mcp.example.com/mcp
    • OAuth客户端ID：您生成的客户端ID
    • OAuth客户端密钥：您生成的客户端密钥

服务器将颁发有效期为1小时的访问令牌。Claude Chat自动处理令牌刷新。

端点

在HTTP模式下运行时：

端点 方法 身份验证 描述
/health GET 否 健康检查，返回状态和能力级别
/oauth/token POST 否 OAuth 2.0令牌端点
/mcp POST 是 MCP协议端点
/ POST 是 /mcp的别名

测试

# Test health endpoint
curl https://mcp.example.com/health

# Get an access token
curl -X POST https://mcp.example.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

# Use the token
curl https://mcp.example.com/mcp \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

能力级别

级别 名称 功能
1 监视器 只读：容器状态、日志、统计数据、系统信息、服务运行状况
2 操作 1级+启动/停止/重启容器和服务
3 配置 级别2+读写文件、配置、卷、网络
4 管理 级别3+写入配置、创建/删除容器、执行命令

推荐：从1级开始，根据需要增加。

可用工具

1级-监视器

  • docker_list_containers -列出所有容器
  • docker_container_logs -获取容器日志
  • docker_container_stats -获取容器CPU/内存统计信息
  • system_info -获取主机系统信息
  • opnsense_status -获取OPNsense状态
  • truenas_status -获取TrueNAS池状态
  • truenas_alerts -获取TrueNAS警报
  • proxmox_status -获取Proxmox群集状态
  • proxmox_list_vms -列出所有虚拟机和容器
  • proxmox_vm_status -获取VM/容器状态
  • home_assistant_status -获取家庭助理版本和实体计数
  • home_assistant_list_entities -列出所有实体（灯、开关、传感器）
  • home_assistant_get_entity -获取特定实体状态和属性

2级-操作

  • docker_restart_container -重新启动容器
  • docker_start_container -启动容器
  • docker_stop_container -停止容器
  • opnsense_service_restart -重新启动OPNsense服务
  • proxmox_start_vm -启动VM/容器
  • proxmox_stop_vm -停止VM/容器
  • proxmox_shutdown_vm -优雅地关闭VM/容器
  • proxmox_reboot_vm -重新启动VM/容器

级别3-配置

  • docker_read_compose -阅读docker-compose.yml
  • docker_list_volumes -列出Docker卷
  • docker_list_networks -列出Docker网络
  • docker_inspect_container -检查集装箱详细信息
  • truenas_list_datasets -列出ZFS数据集
  • truenas_dataset_info -获取数据集详细信息
  • proxmox_vm_config -获取VM/容器配置
  • proxmox_list_storage -列出Proxmox存储
  • proxmox_list_nodes -列出群集节点
  • home_assistant_get_config -获取家庭助理配置
  • home_assistant_error_log -获取错误日志

第4级-管理

  • docker_write_compose -写docker-compose.yml
  • docker_compose_up -部署堆栈
  • docker_compose_down -删除堆栈
  • docker_exec -在容器中执行命令
  • truenas_create_snapshot -创建ZFS快照
  • proxmox_create_snapshot -创建VM/容器快照
  • proxmox_delete_vm -删除VM/容器

发展

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Type check
npx tsc --noEmit

安全须知

  • API密钥应保密并定期轮换
  • 从您需要的最低能力级别开始
  • 对于第四级 /opt/stacks 安装必须 :rw 而不是 :ro
  • 容器需要访问Docker套接字进行容器管理
  • 默认情况下，OPNsense和TrueNAS API使用自签名证书

故障排除

容器无法启动

# Check logs
docker compose logs homelab-mcp

# Common issues:
# - Missing API_KEY in .env
# - Invalid CAPABILITY_LEVEL (must be 1-4)
# - Docker socket not accessible

工具故障

# Test OPNsense API
curl -k -u "key:secret" https://10.0.0.1/api/core/system/status

# Test TrueNAS API
curl -k -H "Authorization: Bearer YOUR_KEY" https://10.0.0.105/api/v2.0/system/info

# Test Home Assistant API
curl -H "Authorization: Bearer YOUR_TOKEN" http://10.0.0.103:8123/api/

# Check network connectivity from container
docker exec homelab-mcp ping 10.0.0.1

权限问题

如果需要级别4（对堆栈的写访问权限），请更新卷装载：

volumes:
  - /opt/stacks:/opt/stacks:rw  # Change from :ro to :rw

许可证

麻省理工学院

贡献

问题和拉取请求欢迎！

相关 MCP