AI导哈

Proxmox自动化编排器

MCP Server for Proxmox是一个实时自动化编排工具，通过集成Proxmox的事件系统（如电子邮件、WebSocket事件等）实现即时问题感知和自动修复，适用于Proxmox环境的自动化管理和AI集成。

  • by JerichoJack
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 JerichoJack/Proxmox-MCP

使用说明

🧠 Proxmox 的 MCP 服务器

这个（或“它”） Proxmox的MCP服务器 是真正的 实时自动化编排器 适用于您的Proxmox环境。
通过摄入 电子邮件 和 WebSocket 事件 直接从您的PVE和PBS节点，MCP服务器能够在您登录之前即时发现问题并自动进行修复。

这个项目填补了……之间的空白 Proxmox的事件系统 以及您的自动化或人工智能层，使MCP代理能够立即对节点、虚拟机或备份事件采取行动。

🚀 为什么事件摄入至关重要

Proxmox通过以下方式生成有价值的数据实时报告：

  • 电子邮件通知 （警报、备份结果、硬件事件）
  • WebSocket 事件 （虚拟机启动/停止，迁移进度，用户界面更新）
  • 外部集成 （Gotify通知，Discord网络钩子）

MCP服务器接收所有这些数据源并提供：

  • A. 实时状态视图 所有节点、虚拟机和PBS作业的。
  • 结构化事件转发 转交给MCP代理商进行下游处理。
  • 自动化故障排除 以及通过脚本或AI逻辑进行修复。
  • 多渠道通知 (Gotify, Discord, 电子邮件, Webhooks)。
  • Proxmox原始信号与您的自动化堆栈之间的统一桥梁。

🧩 架构概述

┌───────────────────────────────┐
│           MCP Server          │
│ proxmox-mcp-server            │
│                               │
│  ├── REST & WebSocket Client  │ ← Subscribes to PVE/PBS events
│  ├── Event Ingestion Engine   │ ← Parses, filters, normalizes events
│  ├── Event Dispatcher         │ ← Pushes structured events to MCP Agent
│  ├── Diagnostic Engine        │ ← Triggers auto-troubleshooting Agents
│  ├── Command Tools            │
└──────────────┬────────────────┘
               │
               ▼
┌───────────────────────────────┐
│             MCP Agent         │
│  Receives event stream,       │
│  sends notifications (Discord,│
│  Home Assistant, email),      │
│  or invokes troubleshooting.  │
└───────────────────────────────┘

🧱 项目结构

Proxmox-MCP/
├── core/                                       # Core functionality
│   ├── api_tester.py                          # API connectivity testing
│   ├── config.py (MCPConfig)                  # Configuration management
│   ├── event_dispatcher.py                    # Event dispatching
│   ├── event_listener.py                      # Event listening base
│   ├── manager.py (MCPManager)                # MCP Manager
│   ├── proxmox_api.py                         # Proxmox API client wrapper
│   └── utils.py                               # Logging and helper utilities
├── modules/
│   ├── Enhanced_Files/                        # Enhanced documentation & examples
│   │   ├── Discord ChatBot.json               # n8n Discord ChatBot Workflow
│   │   ├── 🤖Proxmox MCP Agent Workflow - Enhanced.json # Advanced AI Agent Workflow
│   │   ├── ENHANCED_README.md                 # Enhanced features documentation
│   │   ├── QUICK_START.md                     # Quick start guide
│   │   └── roadmap.md                         # Project roadmap
│   ├── input/                                 # Event ingestion modules
│   │   ├── base.py                            # BaseListener class
│   │   ├── discord_listener.py                # Discord webhook listener
│   │   ├── email_listener.py                  # Email alert listener
│   │   ├── gotify_listener.py                 # Gotify stream listener
│   │   ├── syslog_listener.py                 # Syslog UDP listener
│   │   └── websocket_listener.py              # WebSocket event listener
│   ├── output/                                # Event dispatch / notification modules
│   │   ├── base.py                            # BaseNotifier class
│   │   ├── discord_notifier.py                # Discord notifier
│   │   └── gotify_notifier.py                 # Gotify notifier
│   └── Test/                                  # Test suite
│       ├── test_connection.py
│       ├── test_discord.py
│       ├── test_enhanced_server.py
│       ├── test_mcp_server.py
│       └── ... (additional test files)
├── main.py                                    # Unified Production Entry Point
├── mcp_server.py                              # MCP stdio Server (local n8n)
├── mcp_server_http.py                         # MCP HTTP/WebSocket Server (remote n8n)
├── .env.example                               # Example configuration file
├── requirements.txt                           # Python dependencies
└── README.md                                  # This file

⚙️ 配置概览

这个（或：那个） .env 文件控制MCP服务器如何连接到Proxmox以及如何处理事件。
每个部分都可以根据您的部署和通知偏好进行切换设置。

  • 独立实验室、集群实验室或混合实验室支持
  • 钥匙 LAB_CONFIGURATION 允许您定义您的实验室是由独立节点、集群节点还是两者的组合构成。
  • 事件监听器可以按类型（WebSocket、电子邮件、Syslog、Gotify、Discord）进行切换。
  • 通知器可以根据后端（当前支持Discord和Gotify）进行切换。
  • 节点凭据、令牌和主机信息按节点存储在.env部分中。

⚠️ 注： 查看完整内容 .env.example 在存储库中用于结构和支持的键。

🏗️ 主要特点

  • 统一生产环境 – ✅ 单一入口点，配备 main.py
  • 全面测试 – ✅ 完整连接性验证与 --test-connection
  • MCP协议集成 – ✅ 适用于n8n的生产就绪MCP服务器
  • AI代理工作流 – ✅ 完成n8n智能自动化示例
  • 多节点支持 – ✅ 单独、集群和混合的Proxmox环境
  • 实时事件处理 – ✅ WebSocket、Email、Syslog 和 API 事件摄入
  • 智能通知 – ✅ Discord、Gotify 与智能路由集成
  • 自然语言接口 – ✅ 用于对话式Proxmox管理的Discord聊天机器人
  • 审批工作流 – ✅ 关键操作中的人工监督AI代理

🛠 可用的MCP工具

stdio（标准输入输出库）和mcp_server.py) 和 HTTP/WebSocket (mcp_server_http.py) 服务器提供全面的工具来管理您的Proxmox基础设施：

核心基础设施管理

  • get_cluster_status - 获取Proxmox集群的全面状态，包括节点、资源和健康状况
  • get_nodes - 获取所有Proxmox节点的详细信息，包括状态和资源
  • get_node_status - 获取特定Proxmox节点的详细状态，包括CPU、内存、存储使用情况
  • check_node_health - 对Proxmox节点进行全面健康检查，包括连接性和资源状态

虚拟机操作

  • get_vms - 获取全面的虚拟机信息，包括状态、配置和性能
  • execute_vm_command - 在虚拟机上执行命令（启动、停止、关机、重启、重新启动、挂起、恢复、重置、状态、配置）

容器管理

  • get_lxcs - 获取全面的LXC容器信息，包括状态和配置
  • execute_lxc_command - 在LXC容器上执行命令（启动、停止、关机、重启、重新启动、挂起、恢复、状态检查、配置）

存储与备份管理

  • get_storage - 获取详细的存储信息，包括使用情况、内容以及健康状态
  • get_backup_info - 获取备份作业信息和状态

高级操作

  • get_node_tasks - 获取节点的最近任务和操作
  • get_network_info - 获取网络配置和接口信息

通知

  • send_notification - 通过配置的渠道（Discord、Gotify）发送通知

可用工具总数： 13款全面工具，满足Proxmox全方位管理需求

🔄 旋转（循环、反复） 功能一致性： 两种服务器实现（stdio 和 HTTP）提供了相同的功能工具，确保无论采用哪种部署方法，都能获得一致的体验。

🚀 开始使用

快速入门（生产环境）

# Clone repository and setup
git clone https://github.com/JerichoJack/Proxmox-MCP.git
cd Proxmox-MCP
pip install -r requirements.txt

# Copy and configure environment
cp .env.example .env
# Edit .env with your Proxmox credentials and preferences

# Test all connections
python3 main.py --test-connection

# Start MCP server for n8n integration
python3 main.py --mcp-server

生产使用

统一的 main.py 作为单一入口点，具有两种主要模式：

🔍 连接测试：

python3 main.py --test-connection
  • 测试所有配置的PVE/PBS节点的连接性
  • 验证输入/输出模块的功能
  • 验证MCP服务器协议初始化
  • 提供全面的系统健康检查

🔌 MCP 服务器模式（stdio）：

python3 main.py --mcp-server
  • 启动增强型MCP服务器以实现n8n集成
  • 使用stdio接口进行本地MCP客户端连接
  • 全面的Proxmox基础设施管理
  • 全套先进的工具和功能

🌐 MCP HTTP 服务器模式（远程）：

python3 main.py --mcp-http --host 0.0.0.0 --port 8000
  • 启动增强型HTTP/WebSocket MCP服务器
  • 支持通过网络进行远程n8n连接
  • 与stdio服务器具有相同的功能集
  • 非常适合分布式部署

🛠️ 增强的MCP工具与功能

现在，stdio 和 HTTP MCP 服务器都提供了 完全相同的综合功能：

🏗️ 核心基础设施管理

  • get_cluster_status - 全面的集群健康状态和资源概览
  • get_nodes - 含有性能指标的详细节点信息
  • get_node_status - 特定节点状态，包括CPU、内存、存储
  • check_node_health 连接性与API健康状态验证

🖥️ 虚拟机操作

  • get_vms - 列出虚拟机的状态、配置和性能数据
  • execute_vm_command - 完整的虚拟机生命周期管理：
    • start， stop， shutdown （优雅的/勉强的）
    • restart， reboot， suspend， resume， reset
    • status， config - 查询当前状态和配置

📦 容器管理

  • get_lxcs - LXC 容器信息和状态
  • execute_lxc_command - 完整的集装箱生命周期管理：
    • 与虚拟机相同的命令集，但针对容器进行了特定优化

💾 存储与备份监控

  • get_storage - 存储利用率、健康状况和容量分析
  • get_backup_info - 备份作业状态和调度信息
  • get_node_tasks - 最近的操作、任务历史和错误追踪

🌐 网络与运营

  • get_network_info - 网络配置和接口状态
  • send_notification - 多渠道通知（Discord、Gotify）

🤖 人工智能就绪提示（或：适用于AI的提示）

  • proxmox_health_check - 指导性的基础设施健康评估
  • proxmox_status_report - 提供包含建议的全面报告
  • proxmox_vm_management - 虚拟机操作最佳实践
  • proxmox_storage_analysis - 存储优化指南
  • proxmox_incident_response - 系统的故障排除程序

📚 资源

  • proxmox://config - 当前的Proxmox MCP服务器配置
  • proxmox://nodes - 配置节点列表及连接状态
  • proxmox://capabilities - 服务器功能和工具说明
  • proxmox://status - 当前服务器状态和健康状况

摘要： 13款工具 + 5个AI提示 + 4种资源 = 全面的Proxmox管理平台

🧩 n8n AI代理集成

这个项目包含了用于智能Proxmox管理的完整n8n工作流示例：

🎯 工作流程示例

1. Discord聊天机器人 (modules/Enhanced_Files/Discord ChatBot.json)

  • 用于Proxmox查询的自然语言接口
  • 通过Discord处理用户命令
  • 将复杂请求路由到专门的AI代理
  • 支持简单查询和复杂基础设施管理

2. Proxmox MCP 代理 (modules/Enhanced_Files/🤖Proxmox MCP Agent Workflow - Enhanced.json)

  • 用于Proxmox基础设施管理的高级AI代理
  • 使用MCP工具进行实时系统监控
  • 结合用户审批工作流的智能决策
  • 全面的状态报告与自动修复

🔄 集成流程

Discord User → ChatBot Agent → Proxmox MCP Agent → MCP Server → Proxmox Infrastructure
     ↑                                ↓
     └─────────── Response & Status Updates ──────────┘

📋 n8n MCP 客户端配置

将n8n连接到您的Proxmox MCP服务器有两种方法：

选项1：本地安装（stdio）- 相同的增强功能

如果你能在与n8n相同的机器上安装MCP服务器：

# On your n8n server
git clone https://github.com/JerichoJack/Proxmox-MCP.git /opt/Proxmox-MCP
cd /opt/Proxmox-MCP
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your Proxmox server credentials

# Start enhanced stdio server
python3 main.py --mcp-server

配置您的MCP客户端节点：

{
  "parameters": {
    "options": {
      "connection": {
        "type": "stdio",
        "command": "python3",
        "args": ["/opt/Proxmox-MCP/mcp_server.py"],
        "workingDirectory": "/opt/Proxmox-MCP"
      }
    }
  }
}

选项2：远程服务器（WebSocket）⭐ 相同的增强功能

如果你的n8n和Proxmox MCP服务器位于不同的机器上：

# On your Proxmox MCP server machine
git clone https://github.com/JerichoJack/Proxmox-MCP.git /root/Proxmox-MCP
cd /root/Proxmox-MCP
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your Proxmox server credentials

# Start enhanced HTTP/WebSocket server
python3 main.py --mcp-http --host 0.0.0.0 --port 8000

配置您的MCP客户端节点：

{
  "parameters": {
    "options": {
      "connection": {
        "type": "websocket",
        "endpoint": "ws://YOUR-SERVER-IP:8000/ws"
      }
    }
  }
}

🎯（瞄准目标） 两种服务器模式现在都提供了完全相同的功能性 - 根据您的部署架构来选择，而不是基于功能差异！

替换 YOUR-SERVER-IP 使用您MCP服务器机器的实际IP地址。

连接示例

对于您当前的设置（n8n部署在独立服务器上）：

{
  "nodes": [
    {
      "parameters": {
        "options": {
          "connection": {
            "type": "websocket",
            "endpoint": "ws://192.168.1.100:8000/ws"
          }
        }
      },
      "type": "@n8n/n8n-nodes-langchain.mcpClientTool",
      "typeVersion": 1.2,
      "position": [1200, 592],
      "id": "bcc9b8b5-9b94-4f73-81de-ea00dd4c9ba6",
      "name": "MCP Client"
    }
  ]
}

服务器管理命令

启动增强型标准I/O服务器（本地n8n）：

python3 main.py --mcp-server

全面的功能集：13种工具 + 5个AI提示 + 4种资源

启动增强型HTTP服务器（远程n8n）：

python3 main.py --mcp-http --host 0.0.0.0 --port 8000

相同的功能集：13个工具 + 5个AI提示 + 4个资源

测试连接并验证设置：

python3 main.py --test-connection

健康检查（HTTP服务器）：

curl http://YOUR-SERVER-IP:8000/health

✨ 功能对等已实现现在，这两台服务器都提供了完全相同的全面Proxmox管理功能！

🧩 增强的用例

🤖 人工智能驱动的基础设施管理

  • 智能健康监测AI代理持续使用（某种方法或工具）评估集群健康状况 check_node_health
  • 预测性维护自动化分析 get_node_tasks 以识别潜在问题
  • 智能资源分配利用全面的AI驱动虚拟机（VM）/轻量级容器（LXC）管理 get_vms/get_lxcs 数据

📊 高级运营与分析

  • 容量规划AI分析 get_storage 扩张建议的趋势
  • 性能优化利用详细节点资源数据的智能虚拟机放置
  • 备份策略通过AI增强的备份监控 get_backup_info 具有故障预测功能

🔔 智能通知与响应

  • 情境感知警报利用严重性分析和历史数据的智能通知
  • 自然语言接口Discord聊天机器人能回答诸如“哪些虚拟机需要关注？”之类的复杂问题
  • 自动化修复人工智能代理在获得人类批准后执行安全恢复程序

🌐 跨平台集成

  • 多渠道通信在Discord、Gotify和其他平台上的统一通知
  • 事件驱动的工作流对Proxmox事件的智能升级自动响应
  • 分布式管理远程HTTP服务器支持从任何地点进行管理

🏗️ 设置与安装

📦 requirements.txt（文件名，可译为“需求文件.txt”或保持原样，因为“requirements.txt”在编程领域是通用的文件名）

以下Python包是必需的：

mcp
proxmoxer
requests
aiohttp
aiohttp-cors
python-dotenv
configparser
apscheduler
gotify
websockets
fastapi
uvicorn
pydantic

使用以下命令安装所有依赖项：

pip install -r requirements.txt

先决条件

  • Python 3.10及以上版本
  • pip 用于依赖管理
  • 具有API访问权限或已启用事件钩子的Proxmox VE环境

克隆仓库

git clone https://github.com/JerichoJack/Proxmox-MCP.git
cd Proxmox-MCP

安装依赖项

pip install -r requirements.txt

Proxmox API 设置

为了使MCP服务器能够接收数据并与您的Proxmox环境进行交互，您需要创建一个专用的 API用户 具有受限权限。
这个过程应该对两者都重复进行 Proxmox VE（PVE） 和 Proxmox备份服务器 (PBS) 如果你两者都在用的话。

🧠 第一步：创建专用API用户（PVE）

  1. 登录到您的 Proxmox VE 网页用户界面。
  2. 导航至 数据中心 → 权限 → 用户。
  3. 点击 添加 → 用户。
  4. 输入用户名，例如：
    mcp@pve
  5. 选择 领域/范围： Proxmox VE authentication server （或者如果您使用LDAP，则使用另一个）。
  6. 设定一个 安全密码 并点击 添加。

步骤2：创建API令牌（可选，但建议）

如果你更喜欢 基于令牌的身份验证 （对服务而言更安全）：

  1. 导航至 数据中心 → 权限 → API令牌。
  2. 点击 添加。
  3. 选择您刚刚创建的用户（mcp@pve）。
  4. 给令牌分配一个ID，例如：。 mcp-token.
  5. 取消选中 特权分离 如果您的MCP服务器需要完全访问所分配的角色。
  6. 复制 令牌ID 和 秘密 — 你这些都需要用到 .env 文件。

🔐 步骤3：分配权限

  1. 首选 数据中心 → 权限 → 添加 → 用户权限.
  2. 选择：
    • 路径： / （或者如果您愿意，也可以限制到特定节点）
    • 用户： mcp@pve
    • 角色： PVEAuditor （只读）
      或者 PVEAdmin （用于完整事件和控制访问）。
  3. 点击 添加。

⚠️ 注： 如果你的MCP服务器与PVE运行在同一主机上，你可以使用 localhost 用于主机地址。
确保MCP进程用户能够访问Proxmox API端口（默认 8006）。

根据全局信息，翻译目标语言为中文，且“API”一词需保留原样。原文内容为“Proxmox Backup Server (PBS) API Setup”，其译文为“Proxmox备份服务器(PBS)API设置”

如果您也希望MCP监听来自您的（系统/服务）的与备份相关的事件 Proxmox 备份服务器在那里创建一个类似的用户。

步骤1：在PBS上创建用户

  1. 登录到您的 PBS 网页用户界面。
  2. 首选 访问控制 → 用户 → 添加。
  3. 创建一个用户：
    mcp@pbs
  4. 设置一个安全的密码。

步骤2：分配角色和权限

  1. 首选 访问控制 → 权限 → 添加。
  2. 选择：
    • 路径： /
    • 用户： mcp@pbs
    • 角色： Audit （只读） 或者 Admin （完全访问）。

第三步：（可选）创建API令牌

类似于PVE（玩家对环境/玩家对版本）：

  • 首选 访问控制 → API令牌.
  • 点击 添加。
  • 为（某物/某人）创建令牌 mcp@pbs。
  • 复制令牌和密钥以用于 .env。

✅ 最后一步：测试连接性

配置好您的 .env 文件，使用内置的连接测试工具验证您的设置：

# Test all configured nodes and IO modules
python main.py --test-connection

什么 --test-connection 验证：

  • ✅ 根据上述信息，以下是原文内容的翻译：“PVE/PBS API 访问” – 测试每个配置节点的凭据和连接性
  • ✅ WebSocket 端点 – 验证订阅实时事件流的能力
  • ✅ 输入监听器 – 测试Gotify流、Discord Webhook和Syslog端口绑定
  • ✅ 输出通知器 – 通过Gotify和Discord（如果已启用）发送测试通知
  • ✅ 配置解析 – 验证 .env 结构和所需参数

预期输出：

🔗 Testing connectivity to configured nodes...
✅ PVE Node 'pve-main' connectivity test passed
✅ PBS Node 'pbs-main' connectivity test passed
🔔 Testing Gotify output notifier...
✅ Gotify output test sent successfully
🔔 Testing Gotify input listener (stream)...
✅ Gotify input test stream succeeded

🎉 All nodes and IO modules are reachable and ready!

一旦所有测试通过，您就可以以您偏好的模式启动MCP服务器：

# Start MCP stdio server (for local n8n)
python3 main.py --mcp-server

# OR start MCP HTTP server (for remote n8n)
python3 main.py --mcp-http --host 0.0.0.0 --port 8000

🔔 通知系统

  • [x] 电子邮件 – 阅读Proxmox的电子邮件警报
  • [x] WebSocket – 订阅实时 Proxmox 事件流
  • [x] Syslog（系统日志） – 监听来自Proxmox节点的UDP syslog消息
  • [x] Gotify（可直接作为专有名词使用，无需翻译，若需解释性翻译，可译为“一个通知推送工具/服务”） – ✅ 完整的输入/输出实现，支持流处理和通知功能
  • [x] Discord（一种即时通讯和语音聊天软件） – ✅ 完整的输入/输出实现，支持Webhooks和丰富的嵌入功能
  • [⚙]（齿轮图标，通常表示设置、选项或调整功能） Ntfy（注：这可能是一个特定应用或服务的名称，直接翻译为中文可能无具体含义，因此保持原样） – 计划中的

所有通知后端都使用统一的接口；添加一个新的通知器只需实现 .send(title, message)。

🛠️ 故障排除

常见问题

❌ 未找到配置文件 '.env'

# Copy the example configuration
cp .env.example .env
# Edit with your Proxmox credentials
nano .env

❌ n8n中的MCP服务器连接问题

  • 确保工作目录设置为Proxmox-MCP文件夹
  • 为 Python 命令使用绝对路径
  • 验证python3是否在你的PATH环境变量中： which python3
  • 手动测试： python3 mcp_server.py （应显示连接信息）

❌ 部分连接测试失败

  • 检查与Proxmox节点的网络连接
  • 验证API凭据在 .env
  • 确保防火墙允许连接到所需的端口
  • 检查Discord/Gotify的令牌和Webhook URL

❌ n8n工作流执行错误

  • 确保MCP服务器正在运行： python3 main.py --mcp-server
  • 检查n8n MCP客户端节点配置
  • 验证Discord是否正确传递了channelId
  • 在n8n测试模式下测试单个MCP工具

寻求帮助

  1. 运行诊断： python3 main.py --test-connection
  2. 检查日志在终端输出中查找错误信息
  3. 验证配置评论 .env 文件设置
  4. 审查文件查看 modules/Enhanced_Files/QUICK_START.md 用于快速设置指南
  5. 测试MCP工具使用n8n的测试模式来验证单个工具的功能

🤝 贡献（或“参与贡献”）

欢迎贡献！请提交问题或拉取请求。 首先讨论“问题”部分的主要变化。

📄 许可证

麻省理工学院许可证（MIT License）

Proxmox 的 MCP 服务器 — 一个实时自动化编排器，为您的Proxmox基础设施带来智能与自主性。

相关 MCP