Skip to main content
Glama
enesjakozh
canvrno

Proxmox MCP Server

by canvrno
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

🚀 Proxmox 管理器 - Proxmox MCP 服务器

ProxmoxMCP

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

🏗️ 内置

  • Cline - 自主编码代理 - 使用 Cline 可以加快速度。

  • Proxmoxer - Proxmox API 的 Python 包装器

  • MCP SDK - 模型上下文协议 SDK

  • Pydantic - 使用 Python 类型注释进行数据验证

Related MCP server: MCP Builder

✨ 特点

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

  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

  2. 安装依赖项：

    # Install with development dependencies uv pip install -e ".[dev]"

  3. 创建配置：

    # Create config directory and copy template mkdir -p proxmox-config cp config/config.example.json proxmox-config/config.json

  4. 编辑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 } }

验证安装

  1. 检查 Python 环境：

    python -c "import proxmox_mcp; print('Installation OK')"

  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 网络界面

  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 交互：

获取节点

列出 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 许可证

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/canvrno/ProxmoxMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server