ProxmoxMCP

Name: ProxmoxMCP
Author: canvrno

作者：canvrno176 星标更新：2025-02-20

安装使用来源：spider==github.com

项目介绍

🚀 Proxmox Manager - Proxmox MCP 服务器

ProxmoxMCP

基于Python的模型上下文协议（MCP）服务器，用于与Proxmox虚拟化管理程序交互，提供一个干净的接口来管理节点、虚拟机和容器。

🏗️ 构建工具

Cline - 自主编码代理 - 使用Cline更快地编码。
Proxmoxer - Proxmox API的Python封装器
MCP SDK - 模型上下文协议SDK
Pydantic - 使用Python类型注解进行数据验证

✨ 特性

🤖 完整集成Cline
🛠️ 使用官方MCP SDK构建
🔒 基于令牌的安全认证与Proxmox
🖥️ 管理节点和虚拟机的工具
💻 虚拟机控制台命令执行
📝 可配置的日志系统
✅ 使用Pydantic实现类型安全
🎨 支持自定义主题的丰富输出格式

📦 安装

预备条件

UV 包管理器（推荐）
Python 3.10 或更高版本
Git
具有API令牌凭据的Proxmox服务器访问权限

在开始之前，请确保您拥有：

Proxmox服务器主机名或IP地址
Proxmox API令牌（参见API令牌设置）
已安装UV (pip install uv)

快速安装（推荐）

克隆并设置环境：

# 克隆仓库
cd ~/Documents/Cline/MCP  # 对于Cline用户
# 或者
cd your/preferred/directory  # 手动安装

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

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate  # Linux/macOS
# 或者
.\.venv\Scripts\Activate.ps1  # Windows

安装依赖项：

# 安装开发依赖项
uv pip install -e ".[dev]"

创建配置：

# 创建配置目录并复制模板
mkdir -p proxmox-config
cp config/config.example.json proxmox-config/config.json

编辑 proxmox-config/config.json：

{
    "proxmox": {
        "host": "PROXMOX_HOST",        // 必需：您的Proxmox服务器地址
        "port": 8006,                  // 可选：默认是8006
        "verify_ssl": false,           // 可选：对于自签名证书设置为false
        "service": "PVE"               // 可选：默认是PVE
    },
    "auth": {
        "user": "USER@pve",            // 必需：您的Proxmox用户名
        "token_name": "TOKEN_NAME",    // 必需：API令牌ID
        "token_value": "TOKEN_VALUE"   // 必需：API令牌值
    },
    "logging": {
        "level": "INFO",               // 可选：DEBUG以获取更多细节
        "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
        "file": "proxmox_mcp.log"      // 可选：记录到文件
    }
}

验证安装

检查Python环境：

python -c "import proxmox_mcp; print('安装成功')"

运行测试：
```
pytest
```

验证配置：

# Linux/macOS
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服务器
或连接错误（如果Proxmox详情不正确）

⚙️ 配置

Proxmox API令牌设置

登录到您的Proxmox Web界面
导航至数据中心 -> 权限 -> API令牌
创建一个新的API令牌：
- 选择一个用户（例如，root@pam）
- 输入令牌ID（例如，“mcp-token”）
- 如果需要完全访问权限，则取消选择“特权分离”
- 保存并复制令牌ID和密钥

🚀 运行服务器

开发模式

用于测试和开发：

# 首先激活虚拟环境
source .venv/bin/activate  # Linux/macOS
# 或者
.\.venv\Scripts\Activate.ps1  # Windows

# 运行服务器
python -m proxmox_mcp.server

Cline桌面集成

对于Cline用户，在您的MCP设置文件中添加此配置（通常位于~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json）：

{
    "mcpServers": {
        "github.com/canvrno/ProxmoxMCP": {
            "command": "/绝对路径/to/ProxmoxMCP/.venv/bin/python",
            "args": ["-m", "proxmox_mcp.server"],
            "cwd": "/绝对路径/to/ProxmoxMCP",
            "env": {
                "PYTHONPATH": "/绝对路径/to/ProxmoxMCP/src",
                "PROXMOX_MCP_CONFIG": "/绝对路径/to/ProxmoxMCP/proxmox-config/config.json",
                "PROXMOX_HOST": "您的Proxmox主机",
                "PROXMOX_USER": "用户名@pve",
                "PROXMOX_TOKEN_NAME": "令牌名称",
                "PROXMOX_TOKEN_VALUE": "令牌值",
                "PROXMOX_PORT": "8006",
                "PROXMOX_VERIFY_SSL": "false",
                "PROXMOX_SERVICE": "PVE",
                "LOG_LEVEL": "DEBUG"
            },
            "disabled": false,
            "autoApprove": []
        }
    }
}

为了生成正确的路径，您可以使用以下命令：

# 这将打印带有您的绝对路径填充的MCP设置
python -c "import os; print(f'''{{
    \"mcpServers\": {{
        \"github.com/canvrno/ProxmoxMCP\": {{
            \"command\": \"{os.path.abspath('.venv/bin/python')}\",
            \"args\": [\"-m\", \"proxmox_mcp.server\"],
            \"cwd\": \"{os.getcwd()}\",
            \"env\": {{
                \"PYTHONPATH\": \"{os.path.abspath('src')}\",
                \"PROXMOX_MCP_CONFIG\": \"{os.path.abspath('proxmox-config/config.json')}\",
                ...
            }}
        }}
    }}
}}''')"

重要事项：

所有路径必须是绝对路径
Python解释器必须来自您的虚拟环境
PYTHONPATH必须指向src目录
更新MCP设置后重启VSCode

🔧 可用工具

该服务器提供了以下MCP工具来与Proxmox交互：

get_nodes

列出Proxmox集群中的所有节点。

参数：无

示例响应：

🖥️ Proxmox 节点

🖥️ pve-compute-01
  • 状态：在线
  • 运行时间：⏳ 156天 12小时
  • CPU核心数：64
  • 内存：186.5 GB / 512.0 GB (36.4%)

🖥️ pve-compute-02
  • 状态：在线
  • 运行时间：⏳ 156天 11小时
  • CPU核心数：64
  • 内存：201.3 GB / 512.0 GB (39.3%)

get_node_status

获取特定节点的详细状态。

参数：
- node（字符串，必需）：节点名称

示例响应：

🖥️ 节点：pve-compute-01
  • 状态：在线
  • 运行时间：⏳ 156天 12小时
  • CPU使用率：42.3%
  • CPU核心数：64 (AMD EPYC 7763)
  • 内存：186.5 GB / 512.0 GB (36.4%)
  • 网络：⬆️ 12.8 GB/s ⬇️ 9.2 GB/s
  • 温度：38°C

get_vms

列出集群中的所有虚拟机。

参数：无

示例响应：

🗃️ 虚拟机

🗃️ prod-db-master (ID: 100)
  • 状态：运行中
  • 节点：pve-compute-01
  • CPU核心数：16
  • 内存：92.3 GB / 128.0 GB (72.1%)

🗃️ prod-web-01 (ID: 102)
  • 状态：运行中
  • 节点：pve-compute-01
  • CPU核心数：8
  • 内存：12.8 GB / 32.0 GB (40.0%)

get_storage

列出可用存储。

参数：无

示例响应：

💾 存储池

💾 ceph-prod
  • 状态：在线
  • 类型：rbd
  • 使用情况：12.8 TB / 20.0 TB (64.0%)
  • IOPS：⬆️ 15.2k ⬇️ 12.8k

💾 local-zfs
  • 状态：在线
  • 类型：zfspool
  • 使用情况：3.2 TB / 8.0 TB (40.0%)
  • IOPS：⬆️ 42.8k ⬇️ 35.6k

get_cluster_status

获取集群的整体状态。

参数：无

示例响应：

⚙️ Proxmox 集群

  • 名称：enterprise-cloud
  • 状态：健康
  • 多数票：正常
  • 节点：4 在线
  • 版本：8.1.3
  • 高可用状态：活动
  • 资源：
    - 总CPU核心数：192
    - 总内存：1536 GB
    - 总存储：70 TB
  • 工作负载：
    - 正在运行的虚拟机：7
    - 总虚拟机数：8
    - 平均CPU使用率：38.6%
    - 平均内存使用率：42.8%

execute_vm_command

使用QEMU Guest Agent在虚拟机控制台执行命令。

参数：
- node（字符串，必需）：虚拟机所在节点名称
- vmid（字符串，必需）：虚拟机ID
- command（字符串，必需）：要执行的命令

示例响应：

🔧 控制台命令结果
  • 状态：成功
  • 命令：systemctl status nginx
  • 节点：pve-compute-01
  • 虚拟机：prod-web-01 (ID: 102)

输出：
● nginx.service - 高性能Web服务器和反向代理服务器
   加载：已加载 (/lib/systemd/system/nginx.service; 启用; 默认预设启用)
   活动：活动 (正在运行) 自2025年2月18日星期二15:23:45 UTC以来；2个月3天

要求：
- 虚拟机必须正在运行
- 虚拟机中必须安装并运行QEMU Guest Agent
- 必须在Guest Agent中启用命令执行权限
错误处理：
- 如果虚拟机未运行则返回错误
- 如果找不到虚拟机则返回错误
- 如果命令执行失败则返回错误
- 即使命令返回非零退出码也会包括命令输出

👨‍💻 开发

激活虚拟环境后：

运行测试：pytest
格式化代码：black .
类型检查：mypy .
代码检查：ruff .

📁 项目结构

proxmox-mcp/
├── src/
│   └── proxmox_mcp/
│       ├── server.py          # 主MCP服务器实现
│       ├── config/            # 配置处理
│       ├── core/              # 核心功能
│       ├── formatting/        # 输出格式化和主题
│       ├── tools/             # 工具实现
│       │   └── console/       # 虚拟机控制台操作
│       └── utils/             # 实用工具（认证、日志）
├── tests/                     # 测试套件
├── proxmox-config/
│   └── config.example.json    # 配置模板
├── pyproject.toml            # 项目元数据和依赖项
└── LICENSE                   # MIT License

📄 许可证

MIT License