Cursor Proxmox MCP

cursor-proxmox-mcp

正式的 Cursor ↔ Proxmox VE MCP 集成 — 提供 212 个工具，涵盖 QEMU 虚拟机（包括 guest-agent 网络/文件/来宾信息/fsfreeze，以及 bootstrap_cloudinit_vm / provision_vm / qm_set_vm）、LXC（包括 provision_lxc、bootstrap_docker_lxc、crun Path B、DNS/SSH 助手、deploy_node_app）、统一的来宾电源管理、存储管理（包括 PBS 插件和状态）、集群/任务（包括加入集群）、快照、备份、迁移、高可用、防火墙、访问控制、复制、SDN 写入和应用、ACME 订单/续期、Ceph 状态/存储池及受控的 OSD 创建/销毁、节点网络 CRUD、控制台票据/get_console_connection，以及主机重启/关机。v1.9.0 新增可选的双凭据提权模式（auth_write、D31）+ provision_vm + Cursor day-2 自动批准文档。

仓库： hackmods/cursor-proxmox-mcp

文档：设置指南 · Wiki (docs/wiki/) · 发布 · 安全 · 贡献指南 · API 覆盖范围 · 更新日志

MCP 工具

通过 tools/register.py 注册（由 ProxmoxMCPServer._setup_tools() 调用）——工具清单由 tools/inventory.py / tests/expected_tools.py 锁定（CI 会在清单发生变化时失败）。

Domain	Tools
节点	get_nodes、get_node_status、list_node_networks + 创建/更新/删除 + reload_node_network、get_node_subscription、list_node_certificates、get_node_report、list_node_services、get_node_time、wake_node、reboot_node / shutdown_node（confirm=<node>）
集群 / 任务	get_cluster_status、get_next_vmid、get_task_status、list_tasks、wait_for_task、get_version、get_mcp_capabilities、get_cluster_resources、get_cluster_log、get_cluster_options、get_cluster_join_info、join_cluster（confirm=JOIN）
QEMU	生命周期 + 配置（ISO/cloud-init/net/onboot/tags/description；可选 wait=true）+ get_vm_network / get_vm_guest_info / fsfreeze_vm / fsthaw_vm / push_to_vm / pull_from_vm（来宾 Agent）+ bootstrap_cloudinit_vm / provision_vm（一次性创建或克隆→CI→IP）+ qm_set_vm + get_vm_status、get_vm_rrd_data、控制台票据
LXC	生命周期 + 配置 + 挂起/恢复（CRIU 警告）+ get_lxc_status / get_lxc_network / get_lxc_rrd_data + VNC/SPICE/termproxy；创建时可设置 ssh_public_keys / docker_ready / nameserver / wait / onboot / description / tags；通过可选启用的 主机 SSH + pct 提供 provision_lxc（一次性创建→启动→IP→SSH）/ bootstrap_docker_lxc / prepare_lxc_for_docker（`docker_mode=auto
来宾（统一）	start/stop/shutdown/reboot/delete_guest、get_guest_status、get_guest_pending、move_guest_disk、get_console_connection（guest_type）
快照 / 备份	快照 CRUD/回滚；一次性备份 CRUD；计划备份 list/create/delete_backup_job
存储	列表、内容、list_os_templates、list_isos、下载 URL、定义 CRUD；通过 create_storage(type=pbs) + get_pbs_storage_status 使用 PBS
迁移 / HA	migrate_guest；HA 组 + 资源 CRUD
防火墙	集群 + 来宾规则/选项；别名；IP 集 + CIDR 成员；宏
访问控制	用户、组、角色、ACL、令牌、get_permissions、get_token_permissions
复制	列出/查看状态/运行/创建/更新/删除任务
SDN	区域/vnet/子网 CRUD + 列出控制器/ipam/dns + apply_sdn
ACME	列表 + 创建账户/插件、删除插件、order_acme_certificate / renew_acme_certificate
Ceph	状态、列出存储池/OSD/MON/MGR、存储池 CRUD；受控 OSD 流程：list_node_disks → propose_ceph_osd → create_ceph_osd/destroy_ceph_osd（类型化确认；创建时默认 dry_run=true）
资源池	列出/获取/创建/更新/删除

建议的 Agent 工作流

1. get_next_vmid → list_os_templates / list_isos → list_node_networks
2. provision_lxc / provision_vm（优先使用一次性工具），或 create_lxc / create_vm → wait_for_task → 启动
3. 在执行有风险的更改前运行 create_snapshot → update_*_config → get_guest_pending → 如有需要则重启
4. 按需使用 migrate_guest / HA / 防火墙 / 访问控制 / 复制

不知道来宾类型？ 优先使用统一工具（start_guest、stop_guest、shutdown_guest、reboot_guest、delete_guest、get_guest_status），并设置 guest_type=qemu|lxc。并行的 *_vm / *_lxc 名称仍保留，供现有提示词使用。

安装

前置条件

• uv（推荐）或 Python 3.10+
• Proxmox API 令牌

路径 1 — uvx（推荐）

PyPI 包名为 cursor-proxmox-mcp（控制台脚本：cursor-proxmox-mcp，以及别名 proxmox-mcp-server / proxmox-mcp）。

**注意：**无关的 PyPI 项目 proxmox-mcp-server 使用的是不同的代码库。请务必安装 cursor-proxmox-mcp。

# Install uv if needed:  pip install uv   OR   winget install astral-sh.uv

# After PyPI publish (GitHub Release → publish.yml):
uvx cursor-proxmox-mcp

# From a local checkout (dev / before first publish):
uvx --from . cursor-proxmox-mcp

Cursor MCP（已发布的包 — 无需检出代码）：

{
  "mcpServers": {
    "proxmox": {
      "command": "uvx",
      "args": ["cursor-proxmox-mcp"],
      "env": {
        "PROXMOX_MCP_CONFIG": "C:/Users/YOU/proxmox-config/config.json"
      }
    }
  }
}

从本地检出的代码库运行时，请改用 "args": ["--from", "C:/Users/YOU/Projects/cursor-proxmox-mcp", "cursor-proxmox-mcp"]。

为何使用 uvx：它会将依赖解析到隔离的临时环境中，因此 Cursor 无需依赖手动管理的虚拟环境或 PYTHONPATH。

路径 2 — 从源代码使用 uv

git clone https://github.com/hackmods/cursor-proxmox-mcp.git
cd cursor-proxmox-mcp
uv venv
# Windows: .\.venv\Scripts\Activate.ps1
# Linux/macOS: source .venv/bin/activate
uv pip install -e ".[dev]"
cp proxmox-config/config.example.json proxmox-config/config.json
# Edit host + token, then:
uv run cursor-proxmox-mcp

路径 3 — pip 备用方案

python -m venv .venv
# activate venv
pip install -e ".[dev]"
# optional OpenAPI bridge: pip install -e ".[openapi]"
$env:PROXMOX_MCP_CONFIG="proxmox-config\config.json"   # PowerShell
python -m proxmox_mcp.server

Cursor MCP（直接使用 Python — 请使用绝对路径）：

{
  "mcpServers": {
    "proxmox": {
      "command": "python",
      "args": ["-m", "proxmox_mcp.server"],
      "cwd": "C:/Users/YOU/Projects/cursor-proxmox-mcp",
      "env": {
        "PROXMOX_MCP_CONFIG": "C:/Users/YOU/Projects/cursor-proxmox-mcp/proxmox-config/config.json",
        "PYTHONPATH": "C:/Users/YOU/Projects/cursor-proxmox-mcp/src"
      }
    }
  }
}

拉取新工具后，请在 Cursor 中重启 proxmox MCP 服务。手动启动脚本：start.bat（Windows）/ start.sh（Unix）— 建议在 mcp.json 中使用 uvx cursor-proxmox-mcp。

验证 / 本地 CI

.\scripts\ci-local.ps1

./scripts/ci-local.sh

运行步骤：可编辑安装 → 入口点冒烟测试 → ruff → pytest → 工具清单下限（≥100 个工具）。

故障排除

症状	解决方法
spawn uvx ENOENT	安装 uv（pip install uv 或 winget install astral-sh.uv），然后重启 Cursor
ModuleNotFoundError: proxmox_mcp	使用 uvx/uv run，或者为普通 Python 设置 PYTHONPATH=.../src
ModuleNotFoundError: mcp.server.fastmcp	MCP SDK v2 移除了 FastMCP — 此服务固定使用 mcp<2。请从此检出代码库重新安装（pip install -e ".[dev]" / uvx --from .），以应用此版本上限
PROXMOX_MCP_CONFIG ... must be set	将环境变量指向 proxmox-config/config.json（绝对路径）
身份验证正常，但数据为空 / 出现异常的 403	未配置令牌 ACL 时启用了权限分离 Yes — 请参阅 SETUP.md
HA / 防火墙 / keyctl 返回 403	令牌需要更高权限；条件允许时，优先使用范围受限的 mcp@pve，而不是 root@pam
Cursor 中缺少工具	git pull 后重启 MCP 服务

首次配置集群（令牌、权限分离、Cursor JSON、提示词示例）：SETUP.md。LXC Shell / 运行时 IP 需要选择性启用主机 SSH（authorized_keys、可选的 host_overrides、重新加载 MCP）：SETUP.md — SSH for LXC exec。

配置

proxmox-config/config.json 示例：

{
  "proxmox": {
    "host": "PROXMOX_HOST",
    "port": 8006,
    "verify_ssl": false,
    "service": "PVE"
  },
  "auth": {
    "user": "USER@pve",
    "token_name": "TOKEN_NAME",
    "token_value": "TOKEN_VALUE"
  },
  "logging": {
    "level": "INFO",
    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    "file": "proxmox_mcp.log",
    "verbose": false,
    "tool_calls": true
  }
}

工具调用会记录到日志文件中，格式为 tool_call name=… ok=… duration_ms=…（机密信息会被隐藏）。设置 verbose: true 或环境变量 PROXMOX_MCP_VERBOSE=1，可获取更详细的诊断信息，同时避免 urllib3 的日志噪声。详情请参阅：proxmox-config/README.md — Logging。

在 Proxmox UI 中创建令牌：Datacenter → Permissions → API Tokens。完整操作指南请参阅 SETUP.md — API token & Privilege Separation。

权限分离：保留 Yes（默认值），并向令牌（user@realm!tokenid）授予 ACL。将其设为 No 会使令牌继承用户的全部权限（常见于实验环境的便捷做法；令牌泄露时影响范围更大）。请根据所用工具授予相应角色（HA / 防火墙 / 访问控制需要 PVEAuditor、PVEVMAdmin、Datastore.*、Sys.Audit/Sys.Modify）。

建议在配置中使用 "token_value": "${PROXMOX_TOKEN_VALUE}"，并在 Cursor MCP 配置中设置该环境变量，避免机密信息出现在 JSON 文件中。

安全

此服务可以创建/删除虚拟客户机、更改防火墙/ACL，并运行客户机命令。请将 API 令牌视为生产基础设施凭据。完整策略请参阅：SECURITY.md。

功能

• 通过 proxmoxer 进行令牌认证（JSON 配置 + 可选的 ${ENV} 密钥插值）
• 结构化的 tool_call 审计日志（已脱敏）+ verbose / 环境变量日志覆盖
• 完整的来宾生命周期、快照、vzdump 备份
• 存储内容 + 定义的 CRUD + URL 下载
• 集群 HA、防火墙（规则/别名/ipsets）、访问/ACL/令牌
• 复制作业、SDN 写入 + 应用、ACME 订单/续期、Ceph 状态/存储池、资源池
• 控制台 票据签发 + get_console_connection（VNC/SPICE/termproxy）——无 websocket 代理（D6）
• 将 PBS 作为 PVE 存储插件（不是完整的 PBS 产品管理）；节点网络 CRUD + 重新加载
• uvx / uv / pip / Docker（GHCR）安装方式；mcpo 可选使用 .[openapi]
• 本地 + GitHub CI（ruff + pytest + 覆盖率 + 清单 + 设计不变量）

已确定的非目标（并非缺失——D30）

请勿将以下内容视为计划中的缺口：长期运行的 VNC/SPICE websocket 代理（仅票据——D6）、完整的 PBS 产品管理，或无门控的 Ceph OSD/MON/MGR 创建/销毁。已提供带门控的 OSD 工具；MON/MGR 生命周期仍由 Ceph/PVE 工具管理。

开发

.\scripts\ci-local.ps1

添加工具后：更新 definitions.py、README 表格、.cursor/research/proxmox-api-coverage.md、.cursor/research/next-expansion.md（若要关闭计划中的条目），以及 tests/expected_tools.py。

状态

• 正式覆盖多个领域的 Proxmox API（212 个工具）
• Phase B + Phase D Agent QOL 工具
• Phase F LXC day-2 + Phase F.1 VM 网络/推送 + 创建等待选择启用
• Phase C 轻量功能：节点重启/关机 + 集群加入（类型化确认）
• Phase C 其余功能：SDN 写入 / ACME / Ceph 存储池 / 控制台助手 / PBS 存储 / 节点网络 CRUD
• 带门控的 Ceph OSD 创建/销毁（确认 + 默认试运行）
• v1.0 安全加固、代码设计审计、完整测试套件
• uvx cursor-proxmox-mcp + PyPI/GHCR 发布工作流
• 本地 + GitHub CI，含覆盖率 + 设计不变量

许可证

MIT

致谢

基于 ProxmoxMCP / canvrno/ProxmoxMCP。已扩展为 Cursor IDE 的正式 Proxmox VE 集成。