Proxmox MCP Server 使用说明

项目简介

Proxmox MCP Server (ProxmoxMCP) 是一个基于 Python 开发的 MCP 服务器，它允许大型语言模型 (LLM) 客户端通过标准化的 MCP 协议与 Proxmox 虚拟化环境进行交互。该服务器提供了一系列工具，使 LLM 能够获取 Proxmox 集群的状态信息、管理虚拟机和容器、以及执行其他管理任务。

主要功能点

资源管理: 提供对 Proxmox 节点的、虚拟机、容器和存储资源的访问和管理能力。
工具集成: 内置多种工具，例如：
- 获取 Proxmox 节点列表及其状态。
- 获取指定节点的详细状态信息。
- 获取集群中所有虚拟机的列表及其状态。
- 获取 Proxmox 存储池列表及其使用情况。
- 获取 Proxmox 集群的总体状态。
- 在虚拟机控制台中执行命令。
安全认证: 使用 Proxmox API Token 进行安全认证，保障访问安全。
灵活配置: 支持通过配置文件灵活配置 Proxmox 连接参数和日志级别。
Cline 集成: 特别为 Cline 智能体设计，方便集成到 Cline 工作流中。

安装步骤

环境准备:
- 确保已安装 Python 3.10 或更高版本。
- 确保已安装 Git。
- 确保可以访问 Proxmox 服务器，并已获取 API Token。
- 推荐使用 UV 包管理器，可以先安装 UV ('pip install uv')。

下载代码: 使用 Git 克隆 ProxmoxMCP 仓库到本地：

git clone https://github.com/canvrno/ProxmoxMCP.git
cd ProxmoxMCP

创建虚拟环境: 创建并激活 Python 虚拟环境（推荐使用 UV）：

uv venv
source .venv/bin/activate   # Linux/macOS
.\.venv\Scripts\Activate.ps1  # Windows (PowerShell)

安装依赖: 安装项目依赖，包括开发依赖：

uv pip install -e ".[dev]"

配置 Proxmox 连接信息:

创建配置文件夹并复制配置文件模板：

mkdir -p proxmox-config
cp config/config.example.json proxmox-config/config.json

编辑 'proxmox-config/config.json' 文件，填入您的 Proxmox 服务器连接信息和 API Token。

{
    "proxmox": {
        "host": "您的Proxmox主机地址",
        "port": 8006,
        "verify_ssl": false,
        "service": "PVE"
    },
    "auth": {
        "user": "您的Proxmox用户名@realm",
        "token_name": "您的API Token ID",
        "token_value": "您的API Token Secret"
    },
    "logging": {
        "level": "INFO",
        "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
        "file": "proxmox_mcp.log"
    }
}

注意: 请替换 '您的Proxmox主机地址'、'您的Proxmox用户名@realm'、'您的API Token ID' 和 '您的API Token Secret' 为您实际的信息。

服务器配置 (MCP 客户端配置)

对于 MCP 客户端（例如 Cline），您需要配置服务器的启动命令和相关参数，以便客户端能够连接到 ProxmoxMCP 服务器。以下是 Cline 客户端的 MCP 服务器配置示例，您需要根据您的实际安装路径进行调整：

{
    "mcpServers": {
        "ProxmoxMCP": {  //  服务器名称，在 Cline 客户端中用于标识 ProxmoxMCP 服务器
            "command": "/absolute/path/to/ProxmoxMCP/.venv/bin/python",  //  Python 解释器路径，务必指向虚拟环境中的 Python
            "args": ["-m", "proxmox_mcp.server"],  //  启动服务器的参数，固定为 ["-m", "proxmox_mcp.server"]
            "cwd": "/absolute/path/to/ProxmoxMCP",  //  工作目录，指向 ProxmoxMCP 项目根目录
            "env": {  //  环境变量配置
                "PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP/proxmox-config/config.json"  //  ProxmoxMCP 服务器配置文件路径
            },
            "disabled": false,  //  是否禁用该服务器，设置为 false 表示启用
            "autoApprove": []   //  自动批准的工具列表，目前可以为空
        }
    }
}

重要说明:

'/absolute/path/to/ProxmoxMCP' 需要替换为 ProxmoxMCP 项目在您电脑上的绝对路径。
请确保 'command' 指向的是您在安装步骤中创建的虚拟环境中的 Python 解释器。
'PROXMOX_MCP_CONFIG' 环境变量指向您配置的 'config.json' 文件。
MCP 客户端通常不需要配置 Proxmox 的连接信息（例如 'PROXMOX_HOST', 'PROXMOX_USER' 等），因为这些信息已经由 ProxmoxMCP 服务器通过配置文件进行管理。

基本使用方法

启动服务器: 在激活虚拟环境后，使用以下命令启动 ProxmoxMCP 服务器：

PROXMOX_MCP_CONFIG="proxmox-config/config.json" python -m proxmox_mcp.server

或者在 Windows PowerShell 中：

$env:PROXMOX_MCP_CONFIG="proxmox-config\config.json"; python -m proxmox_mcp.server

请确保 'PROXMOX_MCP_CONFIG' 环境变量指向您的配置文件。

连接 MCP 客户端: 配置您的 MCP 客户端（例如 Cline），使其连接到 ProxmoxMCP 服务器。具体的连接方式请参考您使用的 MCP 客户端的文档。对于 Cline，请按照 "服务器配置 (MCP 客户端配置)" 部分的说明进行配置。
使用工具: 连接成功后，您可以在 MCP 客户端中使用 ProxmoxMCP 服务器提供的工具来管理 Proxmox 环境。例如，在 Cline 中，您可以询问：
- "列出 Proxmox 节点" (对应 'get_nodes' 工具)
- "获取节点 pve-compute-01 的状态" (对应 'get_node_status' 工具，参数为 'node: pve-compute-01')
- "列出所有虚拟机" (对应 'get_vms' 工具)
- "在虚拟机 100 上执行命令 uname -a" (对应 'execute_vm_command' 工具，参数为 'node: pve-compute-01, vmid: 100, command: uname -a')
具体的工具列表和参数请参考仓库 README.md 文档或 ProxmoxMCP 服务器的能力声明。

关键词