AI导哈

Proxmox 虚拟机管理服务器

一个只读的Proxmox MCP服务器，允许LLM代理与您的Proxmox家庭实验室虚拟机交互。

  • by teomarcdhio
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 teomarcdhio/proxmox-mcp

使用说明

Proxmox MCP服务器

一个只读MCP（模型上下文协议）服务器，允许LLM代理与您的Proxmox家庭实验室VM交互。

特性

  • 📋 列出所有虚拟机和容器 跨Proxmox集群
  • 🔍 获取详细的VM信息 包括硬件规格、网络配置和磁盘
  • 📊 监视VM状态 具有实时CPU、内存和I/O指标
  • 📈 历史指标 具有每小时、每天、每周、每月或每年的数据
  • 📸 列出VM快照 查看备份点
  • 🖥️ 集群概述 具有节点状态和聚合资源

所有操作都是 只读的 -您的虚拟机是安全的！

快速开始

1.安装UV（如果尚未安装）

curl -LsSf https://astral.sh/uv/install.sh | sh

2.配置Proxmox凭据

cp .env.example .env
# Edit .env with your Proxmox details

3.在Proxmox中创建一个只读的API令牌

  1. 首选 数据中心 → 权限 → API令牌
  2. 点击 添加
  3. 选择一个用户（或创建一个新用户 PVEAuditor 角色）
  4. 设置令牌ID（例如。， homelab-mcp)
  5. 取消选中 如果使用审计员用户，则为“特权分离”
  6. 复制令牌密钥（仅显示一次！）

推荐：创建一个专门的审核员用户

# SSH to your Proxmox server
pveum user add mcp-reader@pve
pveum acl modify / -user mcp-reader@pve -role PVEAuditor
pveum user token add mcp-reader@pve proxmox-mcp

4.运行服务器

cd proxmox-mcp

# SSE mode (recommended for remote access)
uv run proxmox-mcp --transport sse

# Or stdio mode (for local VS Code/CLI usage)
uv run proxmox-mcp --transport stdio

替代方案：使用pip全局安装

pip install -e .
proxmox-mcp --transport sse

可用工具

工具 说明
list_vms 列出所有VM和容器的基本信息
get_vm_info 获取详细的VM配置和规格
get_vm_status 获取当前运行时状态和指标
get_vm_metrics 获取历史性能数据
get_vm_filesystem_info 从VM内部获取磁盘空间（需要来宾代理）
list_nodes 列出所有Proxmox节点
list_vm_snapshots 列出VM的快照
get_cluster_status 获取群集运行状况和总数

配置

所有设置都可以通过环境变量或 .env 文件：

变量 描述 默认值
PROXMOX_HOST Proxmox服务器主机名/IP localhost
PROXMOX_PORT Proxmox API端口 8006
PROXMOX_VERIFY_SSL 验证SSL证书 false
PROXMOX_API_TOKEN_ID API令牌ID(user@realm！托克劳） --
PROXMOX_API_TOKEN_SECRET API令牌机密 -
MCP_SERVER_HOST SSE服务器绑定地址 0.0.0.0
MCP_SERVER_PORT SSE服务器端口 8080

与LLM客户端一起使用

VS代码与GitHub Copilot

添加到您的VS代码 settings.json 或用户 mcp.json:

{
  "servers": {
    "proxmox": {
      "url": "http://your-server:8080/sse"
    }
  }
}

克劳德桌面版

添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "proxmox": {
      "url": "http://your-server:8080/sse"
    }
  }
}

本地stdio模式

对于本地使用，您可以使用stdio传输运行：

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/proxmox-mcp",
        "proxmox-mcp",
        "--transport", "stdio"
      ]
    }
  }
}

查询示例

连接后，您可以询问您的法学硕士：

  • “列出我的所有虚拟机”
  • “VM 100的状态如何？”
  • “显示plex服务器的CPU使用历史记录”
  • “哪些虚拟机当前已停止？”
  • “我的集群使用了多少内存？”

安全说明

  1. 使用API令牌 而不是用户名/密码
  2. 使用PVEAuditer角色 用于真正的只读访问
  3. 在反向代理后面运行 HTTPS已投入生产
  4. 对MCP端口进行防火墙保护 仅适用于受信任的网络

发展

cd proxmox-mcp

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Lint
uv run ruff check src/

许可证

麻省理工学院

相关 MCP