# pve-mcp — Proxmox VE MCP Server

[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)

用 Python 编写的 [Proxmox VE](https://www.proxmox.com/) MCP（Model Context Protocol）服务器。
在 VS Code / Copilot、Claude Desktop 等支持 MCP 的客户端里，用自然语言查看集群状态、管理虚拟机和快照。

- 传输方式：**stdio**
- 认证：**API Token（推荐）** 或 **用户名/密码（ticket）**
- 所有会产生副作用的工具都需要显式 `confirm=true`

## 功能

| 分类 | 工具 | 说明 |
| --- | --- | --- |
| 连接 | `pve_version` | 版本 / 连通性自检 |
| 集群 | `pve_cluster_status` | 节点、仲裁、VM 数量统计 |
| 节点 | `pve_list_nodes` | 节点 CPU / 内存 / 磁盘 / 运行时长 |
| 节点 | `pve_node_status` | 单节点详情（含存储用量） |
| 客户机 | `pve_list_vms` | 列出 VM 与 LXC（可按节点/状态/类型过滤） |
| 客户机 | `pve_get_vm` | 单机状态 + 配置 |
| 客户机 | `pve_list_snapshots` | 快照列表 |
| 客户机 | `pve_list_templates` | 可克隆模板 |
| 客户机 | `pve_guest_agent_*` | Guest Agent 网络接口 / OS 信息（仅 QEMU） |
| 存储 | `pve_list_storage` / `pve_list_isos` | 存储定义、容量、ISO |
| 任务 | `pve_list_tasks` / `pve_task_status` / `pve_wait_task` | 任务查询与等待 |
| 电源 | `pve_vm_power` | start / stop / shutdown / reboot / suspend / resume |
| 克隆 | `pve_clone_vm` | 从模板或 VM 克隆 |
| 快照 | `pve_create_snapshot` / `pve_delete_snapshot` / `pve_rollback_snapshot` | 快照增删回滚 |
| 配置 | `pve_update_vm` | 修改 VM 配置项（如 `memory`、`cores`、`onboot`） |
| 删除 | `pve_delete_vm` | 永久销毁 VM/CT |
| 逃生口 | `pve_api_request` | 任意 API 调用（默认关闭） |

## 安装

```powershell
cd c:\Users\goyuj\Desktop\pve-mcp
python -m pip install -e .
# 或者只装依赖，直接 python -m pve_mcp 运行
```

依赖：`mcp>=2.0`、`httpx>=0.27`（Python 3.10+）。

## 在 Proxmox 上创建 API Token

1. Web UI → **数据中心 → 权限 → API 令牌** → 添加，用户选 `root@pam`（或专用用户），取消勾选「特权分离」或随后单独授权。
2. 复制生成的 **Secret**（只显示一次），Token ID 形如 `root@pam!mcp`。
3. 授权（SSH 到 PVE 节点执行）：

```bash
# 只读
pveum acl modify / --tokens 'root@pam!mcp' --roles PVEAuditor

# 需要开关机 / 快照 / 克隆 / 改配置
pveum acl modify / --tokens 'root@pam!mcp' --roles PVEVMAdmin
```

## 配置

复制 `.env.example` 为 `.env` 并填写（服务器会自动加载项目根目录或当前目录的 `.env`）：

```ini
PVE_HOST=https://192.168.1.10:8006
PVE_TOKEN_ID=root@pam!mcp
PVE_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
PVE_VERIFY_SSL=false   # 自签证书时设为 false
```

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `PVE_HOST` | —（必填） | `host` 或完整 URL，缺省补 `https://` 与 `:8006` |
| `PVE_TOKEN_ID` / `PVE_TOKEN_SECRET` | — | Token 认证（推荐） |
| `PVE_USERNAME` / `PVE_PASSWORD` | — | Ticket 认证（Token 未配置时使用，401 会自动重新登录） |
| `PVE_VERIFY_SSL` | `true` | 是否校验证书 |
| `PVE_TIMEOUT` | `30` | HTTP 超时（秒） |
| `PVE_DEFAULT_NODE` | — | 省略 `node` 参数时使用的节点 |
| `PVE_READ_ONLY` | `false` | `true` 时禁用所有写操作 |
| `PVE_ALLOW_RAW_API` | `false` | `true` 时启用 `pve_api_request` |
| `PVE_ENV_FILE` | — | 指定额外的 env 文件路径 |

也可以在 MCP 客户端的配置里直接写 `env`（VS Code 支持 `${input:...}` / `${env:...}` 占位符）。

### VS Code

仓库内已提供 [.vscode/mcp.json](.vscode/mcp.json)，打开工作区后即可在 MCP 服务器列表里启动 `pve`。
同样可以写入用户级 `mcp.json`：

```json
{
  "servers": {
    "pve": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "pve_mcp"],
      "env": {
        "PYTHONPATH": "c:\\Users\\goyuj\\Desktop\\pve-mcp",
        "PVE_HOST": "https://192.168.1.10:8006",
        "PVE_TOKEN_ID": "root@pam!mcp",
        "PVE_TOKEN_SECRET": "xxxx"
      }
    }
  }
}
```

### Claude Desktop / 其他客户端

```json
{
  "mcpServers": {
    "pve": {
      "command": "python",
      "args": ["-m", "pve_mcp"],
      "env": {
        "PYTHONPATH": "c:\\Users\\goyuj\\Desktop\\pve-mcp",
        "PVE_HOST": "https://192.168.1.10:8006",
        "PVE_TOKEN_ID": "root@pam!mcp",
        "PVE_TOKEN_SECRET": "xxxx"
      }
    }
  }
}
```

安装为可执行命令后（`pip install -e .`）也可以直接 `command: "pve-mcp"`。

## 安全设计

- 写操作（电源、克隆、快照、改配置、删除）必须传 `confirm=true`，否则直接拒绝，不会发出任何请求。
- `PVE_READ_ONLY=true` 可整体冻结写操作。
- `pve_api_request` 默认不可用，需要 `PVE_ALLOW_RAW_API=true`。
- 只接受相对 API 路径，禁止传入绝对 URL（防止凭据被发到别的地址）。
- 凭据只从环境变量 / `.env` 读取，不会出现在工具参数里；`.env` 已在 `.gitignore` 中。

## 开发

```powershell
python -m pip install -e ".[dev]"
python -m pytest -q
```

代码结构：

- [pve_mcp/config.py](pve_mcp/config.py) — 环境变量解析、`.env` 加载、URL 规范化
- [pve_mcp/client.py](pve_mcp/client.py) — PVE API 客户端（Token / Ticket 认证、错误映射、任务轮询）
- [pve_mcp/server.py](pve_mcp/server.py) — MCP 工具定义
- [tests/](tests) — 使用 `httpx.MockTransport` 的单元测试

## License

本项目基于 [MIT License](LICENSE) 发布，Copyright (c) 2026 WindSnowLi。

> 提示：请勿提交你自己的 `.env`。本项目只提供 `.env.example`，所有凭据都应通过环境变量或本机 `.env` 注入。