Proxmox管理平台

一个基于Python的服务器， enables 与Proxmox虚拟机管理程序的交互。它支持安全的身份验证，并提供管理节点、虚拟机、集群和存储的工具。

virtualizationsecurity-and-iam

343 查看 · 2026-07-07 更新

简介

一个基于Python的服务器， enables 与Proxmox虚拟机管理程序的交互。它支持安全的身份验证，并提供管理节点、虚拟机、集群和存储的工具。

简介

一个基于Python的服务器， enables 与Proxmox虚拟机管理程序的交互。它支持安全的身份验证，并提供管理节点、虚拟机、集群和存储的工具。

🚀 Proxmox Manager - Proxmox MCP 服务器

ProxmoxMCP

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

🏗️ 构建工具

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

✨ 功能

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

https://github.com/user-attachments/assets/1b5f42f7-85d5-4918-aca4-d38413b0e82b

📦 安装

前提条件

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

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

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

选项 1：快速安装（推荐）

克隆并设置环境：

# 克隆仓库
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 和密钥

🚀 运行服务器

开发模式

用于测试和开发：

# Activate virtual environment first
source .venv/bin/activate  # Linux/macOS
# OR
.\.venv\Scripts\Activate.ps1  # Windows

# Run the server
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": "/absolute/path/to/ProxmoxMCP/.venv/bin/python",
            "args": ["-m", "proxmox_mcp.server"],
            "cwd": "/absolute/path/to/ProxmoxMCP",
            "env": {
                "PYTHONPATH": "/absolute/path/to/ProxmoxMCP/src",
                "PROXMOX_MCP_CONFIG": "/absolute/path/to/ProxmoxMCP/proxmox-config/config.json",
                "PROXMOX_HOST": "your-proxmox-host",
                "PROXMOX_USER": "username@pve",
                "PROXMOX_TOKEN_NAME": "token-name",
                "PROXMOX_TOKEN_VALUE": "token-value",
                "PROXMOX_PORT": "8006",
                "PROXMOX_VERIFY_SSL": "false",
                "PROXMOX_SERVICE": "PVE",
                "LOG_LEVEL": "DEBUG"
            },
            "disabled": false,
            "autoApprove": []
        }
    }
}

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

# This will print the MCP settings with your absolute paths filled in
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
  • HA 状态: 活动
  • 资源:
    - 总 CPU 核心数: 192
    - 总内存: 1536 GB
    - 总存储: 70 TB
  • 工作负载:
    - 正在运行的 VM 数量: 7
    - 总 VM 数量: 8
    - 平均 CPU 使用率: 38.6%
    - 平均内存使用率: 42.8%

execute_vm_command

通过 QEMU Guest Agent 在 VM 控制台中执行命令。

参数：
- node (字符串，必填)：运行 VM 的节点名称
- vmid (字符串，必填)：VM 的 ID
- command (字符串，必填)：要执行的命令

示例响应：

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

输出：
● nginx.service - 高性能 Web 服务器和反向代理服务器
   已加载：已加载 (/lib/systemd/system/nginx.service; 启用; 供应商预设: 启用)
   活动：正在运行 (自 2025-02-18 15:23:45 UTC 起；2个月3天前)

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

👨‍💻 开发

激活虚拟环境后：

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

📁 项目结构

proxmox-mcp/
├── src/
│   └── proxmox_mcp/
│       ├── server.py          # Main MCP server implementation
│       ├── config/            # Configuration handling
│       ├── core/              # Core functionality
│       ├── formatting/        # Output formatting and themes
│       ├── tools/             # Tool implementations
│       │   └── console/       # VM console operations
│       └── utils/             # Utilities (auth, logging)
├── tests/                     # Test suite
├── proxmox-config/
│   └── config.example.json    # Configuration template
├── pyproject.toml            # Project metadata and dependencies
└── LICENSE                   # MIT License

📄 许可证

MIT 许可证

服务配置

[{'mcpServers': {'github.com/canvrno/ProxmoxMCP': {'args': ['-m', 'proxmox_mcp.server'], 'autoApprove': [], 'command': '/absolute/path/to/ProxmoxMCP/.venv/bin/python', 'cwd': '/absolute/path/to/ProxmoxMCP', 'disabled': False, 'env': {'LOG_LEVEL': 'DEBUG', 'PROXMOX_HOST': 'your-proxmox-host', 'PROXMOX_MCP_CONFIG': '/absolute/path/to/ProxmoxMCP/proxmox-config/config.json', 'PROXMOX_PORT': '8006', 'PROXMOX_SERVICE': 'PVE', 'PROXMOX_TOKEN_NAME': 'token-name', 'PROXMOX_TOKEN_VALUE': 'token-value', 'PROXMOX_USER': 'username@pve', 'PROXMOX_VERIFY_SSL': 'false', 'PYTHONPATH': '/absolute/path/to/ProxmoxMCP/src'}}}}]

来源

来源：github
链接：https://github.com/canvrno/ProxmoxMCP