🚀 Proxmox 管理器 - Proxmox MCP 服务器

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

🏗️ 内置

Cline - 自主编码代理 - 使用 Cline 可以加快速度。
Proxmoxer - Proxmox API 的 Python 包装器
MCP SDK - 模型上下文协议 SDK
Pydantic - 使用 Python 类型注释进行数据验证

✨ 特点

🤖 与 Cline 完全集成
🛠️ 使用官方 MCP SDK 构建
🔒 使用 Proxmox 进行基于令牌的安全身份验证
🖥️ 用于管理节点和虚拟机的工具
💻 VM 控制台命令执行
📝 可配置的日志系统
✅ 使用 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：快速安装（推荐）

克隆并设置环境：
# Clone repository cd ~/Documents/Cline/MCP # For Cline users # OR cd your/preferred/directory # For manual installation git clone https://github.com/canvrno/ProxmoxMCP.git cd ProxmoxMCP # Create and activate virtual environment uv venv source .venv/bin/activate # Linux/macOS # OR .\.venv\Scripts\Activate.ps1 # Windows
安装依赖项：
# Install with development dependencies uv pip install -e ".[dev]"
创建配置：
# Create config directory and copy template mkdir -p proxmox-config cp config/config.example.json proxmox-config/config.json
编辑proxmox-config/config.json ：
{ "proxmox": { "host": "PROXMOX_HOST", # Required: Your Proxmox server address "port": 8006, # Optional: Default is 8006 "verify_ssl": false, # Optional: Set false for self-signed certs "service": "PVE" # Optional: Default is PVE }, "auth": { "user": "USER@pve", # Required: Your Proxmox username "token_name": "TOKEN_NAME", # Required: API token ID "token_value": "TOKEN_VALUE" # Required: API token value }, "logging": { "level": "INFO", # Optional: DEBUG for more detail "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s", "file": "proxmox_mcp.log" # Optional: Log to file } }

验证安装

检查 Python 环境：
python -c "import proxmox_mcp; print('Installation OK')"
运行测试：
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 网络界面
导航至数据中心 -> 权限 -> 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 交互：

获取节点

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

参数：无
响应示例：
🖥️ Proxmox Nodes 🖥️ pve-compute-01 • Status: ONLINE • Uptime: ⏳ 156d 12h • CPU Cores: 64 • Memory: 186.5 GB / 512.0 GB (36.4%) 🖥️ pve-compute-02 • Status: ONLINE • Uptime: ⏳ 156d 11h • CPU Cores: 64 • Memory: 201.3 GB / 512.0 GB (39.3%)

获取节点状态

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

参数：
- node （字符串，必需）：节点的名称
响应示例：
🖥️ Node: pve-compute-01 • Status: ONLINE • Uptime: ⏳ 156d 12h • CPU Usage: 42.3% • CPU Cores: 64 (AMD EPYC 7763) • Memory: 186.5 GB / 512.0 GB (36.4%) • Network: ⬆️ 12.8 GB/s ⬇️ 9.2 GB/s • Temperature: 38°C

获取虚拟机

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

参数：无
响应示例：
🗃️ Virtual Machines 🗃️ prod-db-master (ID: 100) • Status: RUNNING • Node: pve-compute-01 • CPU Cores: 16 • Memory: 92.3 GB / 128.0 GB (72.1%) 🗃️ prod-web-01 (ID: 102) • Status: RUNNING • Node: pve-compute-01 • CPU Cores: 8 • Memory: 12.8 GB / 32.0 GB (40.0%)

获取存储

列出可用的存储。

参数：无
响应示例：
💾 Storage Pools 💾 ceph-prod • Status: ONLINE • Type: rbd • Usage: 12.8 TB / 20.0 TB (64.0%) • IOPS: ⬆️ 15.2k ⬇️ 12.8k 💾 local-zfs • Status: ONLINE • Type: zfspool • Usage: 3.2 TB / 8.0 TB (40.0%) • IOPS: ⬆️ 42.8k ⬇️ 35.6k

获取集群状态

获取整体集群状态。

参数：无
响应示例：
⚙️ Proxmox Cluster • Name: enterprise-cloud • Status: HEALTHY • Quorum: OK • Nodes: 4 ONLINE • Version: 8.1.3 • HA Status: ACTIVE • Resources: - Total CPU Cores: 192 - Total Memory: 1536 GB - Total Storage: 70 TB • Workload: - Running VMs: 7 - Total VMs: 8 - Average CPU Usage: 38.6% - Average Memory Usage: 42.8%

执行虚拟机命令

使用 QEMU Guest Agent 在 VM 的控制台中执行命令。

参数：
- node （字符串，必需）：虚拟机正在运行的节点的名称
- vmid （字符串，必需）：虚拟机的 ID
- command （字符串，必需）：要执行的命令
响应示例：
🔧 Console Command Result • Status: SUCCESS • Command: systemctl status nginx • Node: pve-compute-01 • VM: prod-web-01 (ID: 102) Output: ● nginx.service - A high performance web server and a reverse proxy server Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled) Active: active (running) since Tue 2025-02-18 15:23:45 UTC; 2 months 3 days ago
要求：
- VM 必须正在运行
- 必须在虚拟机中安装并运行 QEMU Guest Agent
- 必须在来宾代理中启用命令执行权限
错误处理：
- 如果虚拟机未运行则返回错误
- 如果未找到 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 许可证

Proxmox MCP Server

Integrations