P

Proxmox管理平台

@canvrno/ProxmoxMCP
0 Stars 349 次浏览 canvrno 更新于 2026-08-23

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

开发者工具
该服务暂未提供标准配置，请参考 README 手动接入

服务介绍

🚀 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：快速安装（推荐）

  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

  2. 安装依赖项：

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

  3. 创建配置文件：

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

  4. 编辑 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"      # 可选：日志文件
    }
}

验证安装

  1. 检查 Python 环境：

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

  2. 运行测试：

    pytest

  3. 验证配置：

    # 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 令牌设置

  1. 登录到您的 Proxmox Web 界面
  2. 导航到数据中心 -> 权限 -> API 令牌
  3. 创建一个新的 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 许可证

查看源码 项目主页

相关 MCP 服务

LeetCode(力扣)
jinzcdev/leetcode-mcp-server
MCP 服务器实现 LeetCode API 集成，支持自动化获取编程题库、用户数据和竞赛信息。
可视化图表-MCP-Server
antvis/mcp-server-chart
这是一个基于AntV的模型上下文协议服务器，用于生成图表。它支持超过20种类型的图表，并且可以与多种桌面应用程序和平台一起使用。
微软Playwright
@microsoft/playwright-mcp
一种模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页交互，而无需使用视觉模型或截图。
MCP上下文模型文档
@upstash/context7-mcp
一种模型上下文协议服务器，它从库中直接获取最新、特定版本的文档和代码示例并将其引入LLM提示中，帮助开发人员在无需过时或虚构信息的情况下获得准确的答案。