使用说明

🚀 Proxmox管理器-Proxmox MCP服务器

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

🏗️ 构建于

克莱恩 -自主编码代理-使用Cline更快。
Proxmoxer -Proxmox API的Python包装器
MCP-SDK -模型上下文协议SDK
派丹蒂克 -使用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 web界面
导航到数据中心->权限->API令牌
创建新的API令牌：
- 选择用户（例如。，root@pam)
- 输入令牌ID（例如“mcp令牌”）
- 如果您想要完全访问权限，请取消选中“特权分离”
- 保存并复制令牌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解释器必须来自您的虚拟环境
Python必须指向src目录
更新MCP设置后重新启动VSCode

🔧 可用工具

服务器提供以下MCP工具用于与Proxmox交互：

get_nodes

列出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%)

get_node_status

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

参数：
- node （string，必填）：节点名称

示例响应：

🖥️ 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

get_vms

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

参数：无

示例响应：

🗃️ 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%)

get_storage

列出可用存储空间。

参数：无

示例响应：

💾 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

get_cluster_status

获取集群的整体状态。

参数：无

示例响应：

⚙️ 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%

execute_vm_命令

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

参数：
- node （string，必填）：运行VM的节点的名称
- vmid （string，必填）：VM的ID
- command （string，必填）：要执行的命令

示例响应：

🔧 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必须正在运行
- 必须在VM中安装并运行QEMU来宾代理
- 必须在来宾代理中启用命令执行权限
错误处理：
- 如果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许可证

使用说明

🚀 Proxmox管理器-Proxmox MCP服务器

🏗️ 构建于

✨ 特性

📦 安装

先决条件

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

验证安装

⚙️ 配置

Proxmox API令牌设置

🚀 运行服务器

发展模式

Cline桌面集成

🔧 可用工具

get_nodes

get_node_status

get_vms

get_storage

get_cluster_status

execute_vm_命令

👨‍💻 发展

📁 项目结构

📄 许可证

相关 MCP

PowerPoint操作服务器

EPICS PV管理服务器

MCP服务器管理工具

PubMed文献检索服务

Shell命令执行服务

随机数生成工具