Proxmox MCP Server

Proxmox MCP Server

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

Category
访问服务器

README

🚀 Proxmox Manager - Proxmox MCP 服务器

ProxmoxMCP

一个基于 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：快速安装（推荐）

  1. 克隆并设置环境：

    # 克隆仓库
cd ~/Documents/Cline/MCP  # 对于 Cline 用户
# OR
cd your/preferred/directory  # 对于手动安装

git clone https://github.com/canvrno/ProxmoxMCP.git
cd ProxmoxMCP

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate  # Linux/macOS
# OR
.\.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('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 Web 界面
  2. 导航到数据中心 -> 权限 -> API 令牌
  3. 创建新的 API 令牌：
    • 选择一个用户（例如，root@pam）
    • 输入令牌 ID（例如，“mcp-token”）
    • 如果您想要完全访问权限，请取消选中“权限分离”
    • 保存并复制令牌 ID 和密钥

🚀 运行服务器

开发模式

用于测试和开发：

# 首先激活虚拟环境
source .venv/bin/activate  # Linux/macOS
# OR
.\.venv\Scripts\Activate.ps1  # Windows

# 运行服务器
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": []
        }
    }
}

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

# 这将打印 MCP 设置，并填充您的绝对路径
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
  • 状态：健康
  • 仲裁：OK
  • 节点：4 个在线
  • 版本：8.1.3
  • HA 状态：活动
  • 资源：
    - CPU 核心总数：192
    - 内存总数：1536 GB
    - 存储总数：70 TB
  • 工作负载：
    - 正在运行的虚拟机：7
    - 虚拟机总数：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 - 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 Guest Agent
    • 必须在 Guest Agent 中启用命令执行权限
  • 错误处理：
    • 如果 VM 未运行，则返回错误
    • 如果未找到 VM，则返回错误
    • 如果命令执行失败，则返回错误
    • 即使命令返回非零退出代码，也包括命令输出

👨‍💻 开发

激活虚拟环境后：

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

📁 项目结构

proxmox-mcp/
├── src/
│   └── proxmox_mcp/
│       ├── server.py          # 主要 MCP 服务器实现
│       ├── config/            # 配置处理
│       ├── core/              # 核心功能
│       ├── formatting/        # 输出格式和主题
│       ├── tools/             # 工具实现
│       │   └── console/       # VM 控制台操作
│       └── utils/             # 实用程序（身份验证、日志记录）
├── tests/                     # 测试套件
├── proxmox-config/
│   └── config.example.json    # 配置模板
├── pyproject.toml            # 项目元数据和依赖项
└── LICENSE                   # MIT 许可证

📄 许可证

MIT 许可证

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选