Proxmox Em Cp

Proxmox MCP服务器

用于通过AI助手管理Proxmox VE基础设施的模型上下文协议（MCP）服务器。可作为npm包、Docker容器或独立的Python应用程序使用。

项目背景

2025年5月，我们推出了带有FastMCP、FastAPI和虚拟环境的原始ProxmoxMCP服务器。基于社区反馈和运营经验，我们将该项目重建为ProxmoxEmCP，这是一个更清晰、更简单的实现，在保持完整功能的同时消除了设置复杂性。此版本直接使用官方MCP SDK，无需虚拟环境依赖即可运行，使部署和维护变得更加容易。

目录

• 快速开始

- -

• 先决条件
• 安装方法

- - - 本地Python - 打开WebUI集成

• 配置

- 环境变量 - 创建API令牌

• AI代理集成
• 可用的MCP工具

- 节点管理 - VM操作 - 集装箱作业 - 存储和备份 - 监控和日志 - 访问控制 - 网络与安全

• 建筑
• 发展
• 故障排除
• 许可证
• 支持

快速开始

npm/npx

# Install globally
npm install -g @puregrain/proxmox-emcp-node

# Or run directly with npx
npx @puregrain/proxmox-emcp-node

Docker Hub

docker run -d \
  --name proxmox-emcp \
  -e PROXMOX_HOST="192.168.1.100" \
  -e PROXMOX_TOKEN_ID="your-token-id" \
  -e PROXMOX_TOKEN_SECRET="your-token-secret" \
  puregrain/proxmox-emcp:latest

先决条件

• Proxmox VE：7.0版或更高版本，已启用API访问
• 对于npm包：Node.js 18+
• 对于Docker：已安装Docker引擎
• 对于本地Python：Python 3.9+
• API代币：在Proxmox中以适当的权限创建

安装方法

npm包

npm包提供了一个不需要Docker的原生Node.js实现。

# Install globally
npm install -g @puregrain/proxmox-emcp-node

# Set environment variables
export PROXMOX_HOST="192.168.1.100"
export PROXMOX_TOKEN_ID="your-token-id"
export PROXMOX_TOKEN_SECRET="your-token-secret"

# Run the server
proxmox-emcp-node

与npx一起使用（无需安装）：

PROXMOX_HOST=192.168.1.100 \
PROXMOX_TOKEN_ID=your-token-id \
PROXMOX_TOKEN_SECRET=your-token-secret \
npx @puregrain/proxmox-emcp-node

Docker容器

使用Docker Compose（推荐）

1. 克隆存储库：

git clone https://github.com/PureGrain/ProxmoxEmCP.git
cd ProxmoxEmCP

1. 配置环境：

cp .env.example .env
# Edit .env with your Proxmox credentials

1. 启动容器：

docker-compose up -d

使用Docker CLI

docker run -d \
  --name proxmox-emcp \
  -e PROXMOX_HOST="192.168.1.100" \
  -e PROXMOX_TOKEN_ID="your-token-id" \
  -e PROXMOX_TOKEN_SECRET="your-token-secret" \
  puregrain/proxmox-emcp:latest

使用GitHub容器注册表

docker run -d \
  --name proxmox-emcp \
  -e PROXMOX_HOST="192.168.1.100" \
  -e PROXMOX_TOKEN_ID="your-token-id" \
  -e PROXMOX_TOKEN_SECRET="your-token-secret" \
  ghcr.io/puregrain/proxmox-emcp:latest

本地Python

# Clone the repository
git clone https://github.com/PureGrain/ProxmoxEmCP.git
cd ProxmoxEmCP

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export PROXMOX_HOST="192.168.1.100"
export PROXMOX_TOKEN_ID="your-token-id"
export PROXMOX_TOKEN_SECRET="your-token-secret"

# Run the server
python mcp_server_stdio.py

打开WebUI集成

对于 打开WebUI 用户，我们提供 ProxmoxWeaver -一个专门的工具，将完整的Proxmox管理功能直接带入您的Open WebUI界面。

ProxmoxWeaver 是一个原生的Open WebUI工具，提供与我们的MCP服务器相同的全面Proxmox VE管理功能，但专门为Open WebUI生态系统设计。

特征：

• 与Open WebUI的工具系统直接集成
• 同样强大的Proxmox管理功能
• 无需额外的容器或服务
• 通过Open WebUI的工具市场进行简单安装

安装：

1. 访问 ProxmoxWeaver存储库
2. 复制工具配置
3. 在Open WebUI中，导航到 工具 → 添加工具
4. 粘贴ProxmoxWeaver配置
5. 在工具设置中配置Proxmox凭据

用途：

安装后，ProxmoxWeaver在Open WebUI中显示为本机工具，允许您：

• 查询和管理虚拟机和容器
• 监控群集运行状况和资源
• 执行命令并创建快照
• 管理存储、备份和模板
• Open WebUI中的所有自然语言交互

这种集成非常适合已经使用Open WebUI的团队，他们希望在没有额外基础设施的情况下添加Proxmox管理功能。

配置

环境变量

创建API令牌

1. 登录Proxmox Web用户界面
2. 引导到 数据中心 → 权限 → API令牌
3. 点击 添加 创建新令牌
4. 配置令牌：

- 用户：选择您的用户（例如。，root@pam) - 令牌ID：选择描述性名称 - 特权分离：取消选中完全用户权限

1. 复制令牌密钥（仅显示一次！）

AI代理集成

配置您的AI助手（Claude Desktop、Cline或任何兼容MCP的客户端）以连接到服务器。

对于npm包

{
  "mcpServers": {
    "proxmox": {
      "command": "npx",
      "args": ["@puregrain/proxmox-emcp-node"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_TOKEN_ID": "your-token-id",
        "PROXMOX_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

Docker容器

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["attach", "proxmox-emcp"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_TOKEN_ID": "your-token-id",
        "PROXMOX_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

可用的MCP工具

节点管理

• get_nodes -列出群集中的所有节点
• get_node_status -获取特定节点的详细状态

VM操作

• get_vms -列出集群中的所有虚拟机
• get_vm_status -获取VM状态和配置
• start_vm -启动虚拟机
• stop_vm -优雅地停止虚拟机
• reboot_vm -重新启动虚拟机
• execute_vm_command -通过QEMU客户代理执行命令
• create_vm_snapshot -创建VM快照
• list_vm_snapshots -列出VM的所有快照
• get_vm_network -获取VM网络配置

集装箱作业（LXC）

• get_containers -列出所有LXC容器
• get_container_status -获取容器状态和配置
• start_container -启动容器
• stop_container -优雅地停止容器
• reboot_container -重新启动容器
• execute_container_command -在容器中执行命令
• create_container_snapshot -创建容器快照
• list_container_snapshots -列出容器快照

存储和备份

• get_storage -列出存储池
• get_storage_details -获取详细的存储池信息
• get_backups -列出具有筛选功能的备份文件
• list_templates -列出VM和容器模板

监控和日志

• get_cluster_status -获取全面的群集运行状况和资源
• get_task_status -检查Proxmox任务状态
• get_recent_tasks -使用筛选列出最近的任务
• get_cluster_log -获取集群范围内的日志条目

访问控制

• get_users -列出所有具有组和令牌的用户
• get_groups -列出所有有成员的组
• get_roles -列出所有角色和权限

网络与安全

• get_firewall_status -获取防火墙状态和规则

建筑

┌─────────────────┐
│   AI Assistant  │
│  (Claude, etc)  │
└────────┬────────┘
         │ MCP Protocol
         ▼
┌─────────────────┐
│   MCP Server    │
│  (Node/Python)  │
└────────┬────────┘
         │ REST API
         ▼
┌─────────────────┐
│  Proxmox VE     │
│    Cluster      │
└─────────────────┘

发展

贡献

1. 克隆该仓库
2. 创建要素分支
3. 进行更改
4. 运行测试： npm test 或 python -m pytest
5. 提交拉取请求

预提交钩子

此项目使用预提交来保证代码质量：

pip install pre-commit
pre-commit install
pre-commit run --all-files

挂钩包括：

• black -Python代码格式化程序
• flake8 -Python linter
• detect-secrets -秘密扫描
• YAML和空格验证

构建Docker镜像

docker build -t proxmox-emcp .

修改服务器

• Node.js版本：在中编辑文件 npm-app/
• Python版本：编辑 mcp_server_stdio.py
• Docker配置：编辑 Dockerfile 和 docker-compose.yml

故障排除

连接问题

• 验证Proxmox是否可访问: `ping

`

• 检查API端口：确保端口8006可访问
• SSL证书：设置 PROXMOX_VERIFY_SSL=false 用于自签名证书

身份验证失败

• 令牌权限：确保令牌具有所需的权限
• 令牌格式：验证 TOKEN_ID 和 TOKEN_SECRET 是正确的
• 用户权限：检查用户是否具有适当的Proxmox权限

查看日志

# Docker logs
docker logs proxmox-emcp

# npm/Node.js - set LOG_LEVEL
LOG_LEVEL=DEBUG npx @puregrain/proxmox-emcp-node

常见问题

• “连接被拒绝”：检查防火墙和Proxmox API服务
• “未经授权”：验证令牌凭据
• “SSL验证失败”：设置 PROXMOX_VERIFY_SSL=false

许可证

该项目根据以下条款获得双重许可：

• MIT许可证：用于开源。请参阅 许可证 文件以获取详细信息。
• 商业许可证：用于专有用途。请参阅 商业许可证.txt 文件以获取详细信息。

如需商业许可咨询，请联系：\[您的电子邮件或网站\]

支持

• 问题:
• 文档: MCP配置指南
• 赞助商:

______________________________________________________________________

作者：SLA Ops，LLC的PureGrain 仓库: