星战科技xingzhan.cloud
返回市场
普罗克西莫克斯-MCP增强版

普罗克西莫克斯-MCP增强版

作者：chajus16 星标更新：2025-10-13
安装使用来源：spider==github.com

项目介绍

Proxmox MCP 增强版 🚀

通过模型上下文协议（MCP）管理 Proxmox 虚拟环境（VE）基础设施的 115 种专用工具

Python 版本 MCP 兼容性 工具数量 状态 许可证

概述

Proxmox MCP 增强版提供了一个完整的模型上下文协议（MCP）服务器实现，用于管理 Proxmox 虚拟环境（VE）基础设施。通过涵盖 Proxmox 管理各个方面的一百一十五种专用工具，该服务器使 AI 助手和自动化系统能够无缝执行复杂的虚拟化任务。

特点

🎯 115 种专用工具

  • 虚拟机管理（9 种工具）：创建、启动、停止、重启、挂起、恢复、迁移、克隆、删除
  • 容器管理（9 种工具）：LXC 容器生命周期管理
  • 存储管理（10 种工具）：创建、删除、启用、禁用、列出、扫描、清理、分配、上传、下载
  • 集群管理（8 种工具）：节点管理、仲裁、资源
  • 监控（2 种工具）：指标、警报、日志、性能
  • 备份与恢复（8 种工具）：自动备份、恢复、调度
  • 网络（6 种工具）：桥接、绑定、VLAN、DNS 配置
  • 高可用性（6 种工具）：HA 组、资源管理、故障转移
  • 防火墙（5 种工具）：规则、组、别名、安全策略
  • 用户管理（3 种工具）：用户、组、角色、权限、令牌
  • API 和资源（1 种工具）：任务管理、资源查询
  • 模板（4 种工具）：虚拟机/容器模板管理
  • 迁移（3 种工具）：实时迁移、存储迁移
  • 快照（4 种工具）：创建、恢复、管理、删除
  • 复制（3 种工具）：配置和管理复制
  • Ceph 存储（5 种工具）：池创建、OSD 管理、监视器、状态、CRUSH 规则
  • ZFS 存储（4 种工具）：池创建、数据集管理、快照、校验
  • SDN/VXLAN（4 种工具）：软件定义网络区域、虚拟网络、子网
  • 自动化（3 种工具）：创建任务、调度自动化、检查状态
  • 报告（3 种工具）：生成报告、调度报告、导出数据
  • ISO 管理（4 种工具） 🆕：动态 ISO 发现、下载、上传、列表

🔐 安全第一

  • TypedDict 类型安全性：每个参数严格类型化，无 Dict[str, Any]
  • 令牌和密码认证：支持两种认证方法
  • SSL/TLS 支持：证书验证的安全通信
  • 权限管理：细粒度访问控制集成

⚡ 现代架构

  • 异步/等待：完全异步操作以优化性能
  • 连接池：高效资源管理
  • MCP 协议：原生模型上下文协议实现
  • 模块化设计：清晰的关注点分离

安装

通过 pip

pip install proxmox-mcp-enhanced

从源代码安装

git clone https://github.com/yourusername/proxmox-mcp-enhanced.git
cd proxmox-mcenhanced
pip install -e .

配置

环境变量

创建一个 .env 文件或设置以下环境变量：

# 必需 - 主机配置
PROXMOX_HOST=your-proxmox-host.example.com
PROXMOX_USER=root@pam

# 认证（选择一种方法）
# 方法 1：API 令牌（推荐）
PROXMOX_TOKEN_NAME=your-token-name
PROXMOX_TOKEN_VALUE=your-token-value

# 方法 2：密码
PROXMOX_PASSWORD=your-password

# 可选设置
PROXMOX_PORT=8006              # 默认值：8006
PROXMOX_VERIFY_SSL=true        # 默认值：true

MCP 配置

添加到您的 MCP 客户端配置中：

{
  "mcpServers": {
    "proxmox": {
      "command": "proxmox-mcp",
      "env": {
        "PROXMOX_HOST": "your-host",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "token-name",
        "PROXMOX_TOKEN_VALUE": "token-value"
      }
    }
  }
}

使用示例

基本虚拟机操作

# 创建新的虚拟机
{
  "tool": "vm_create",
  "arguments": {
    "vmid": 100,
    "node": "pve-node1",
    "name": "test-vm",
    "memory": 2048,
    "cores": 2,
    "storage": "local-lvm",
    "disk_size": "10G"
  }
}

# 启动虚拟机
{
  "tool": "vm_start",
  "arguments": {
    "vmid": 100,
    "node": "pve-node1"
  }
}

容器管理

# 创建 LXC 容器
{
  "tool": "container_create",
  "arguments": {
    "vmid": 200,
    "node": "pve-node1",
    "ostemplate": "local:vztmpl/ubuntu-22.04-standard.tar.gz",
    "hostname": "test-container",
    "memory": 1024,
    "cores": 1,
    "rootfs": "local-lvm:8"
  }
}

高级存储操作

# 创建 Ceph 池
{
  "tool": "ceph_pool_create",
  "arguments": {
    "name": "rbd-pool",
    "size": 3,
    "min_size": 2,
    "pg_num": 128
  }
}

# 创建 ZFS 数据集
{
  "tool": "zfs_dataset_create",
  "arguments": {
    "name": "tank/datasets/test",
    "pool": "tank",
    "compression": "lz4",
    "dedup": "off"
  }
}

SDN/VXLAN 配置

# 创建 VXLAN 区域
{
  "tool": "sdn_zone_create",
  "arguments": {
    "zone": "vxlan-zone",
    "type": "vxlan",
    "peers": ["10.0.0.1", "10.0.0.2"],
    "mtu": 1450
  }
}

ISO 管理 🆕

# 动态搜索操作系统 ISO
{
  "tool": "iso_search",
  "arguments": {
    "os_name": "ubuntu",
    "version": "22.04",
    "variant": "server",
    "architecture": "amd64"
  }
}

# 直接下载 ISO 到 Proxmox 节点
{
  "tool": "iso_download_direct",
  "arguments": {
    "url": "https://releases.ubuntu.com/22.04/ubuntu-22.04.5-live-server-amd64.iso",
    "filename": "ubuntu-22.04-server.iso",
    "node": "pve-node1",
    "checksum_url": "https://releases.ubuntu.com/22.04/SHA256SUMS"
  }
}

# 列出可用的 ISO
{
  "tool": "iso_list_available",
  "arguments": {
    "storage": "local"
  }
}

有关完整的 ISO 下载文档，请参阅 ISO_DOWNLOAD_GUIDE.md。

自动化与报告

# 调度自动备份
{
  "tool": "schedule_create",
  "arguments": {
    "name": "daily-backup",
    "schedule": "0 2 * * *",
    "command": "backup:all",
    "node": "pve-node1"
  }
}

# 生成性能报告
{
  "tool": "performance_report",
  "arguments": {
    "analysis_type": "bottleneck",
    "metrics": ["cpu", "memory", "disk", "network"],
    "recommendations": true
  }
}

工具分类

核心基础设施（41 种工具）

  • 虚拟机管理：9 种工具
  • 容器管理：9 种工具
  • 存储管理：10 种工具
  • Ceph 存储：5 种工具
  • ZFS 存储：4 种工具
  • 集群管理：8 种工具

运营与监控（23 种工具）

  • 监控：2 种工具
  • 备份管理：8 种工具
  • 网络管理：6 种工具
  • 高可用性：6 种工具

安全与访问（15 种工具）

  • 防火墙管理：5 种工具
  • 用户管理：3 种工具
  • API/资源工具：1 种工具
  • 令牌管理：包含在用户工具中

高级功能（22 种工具）

  • 模板：4 种工具
  • 迁移：3 种工具
  • 快照：4 种工具
  • 复制：3 种工具
  • SDN/VXLAN：4 种工具
  • 自动化：3 种工具
  • 报告：3 种工具

架构

项目结构

proxmox-mcp-enhanced/
├── src/
│   └── proxmox_mcp/
│       ├── __init__.py          # 工具注册（115 种工具）
│       ├── base.py              # 基础 ToolHandler 类
│       ├── types.py             # TypedDict 定义
│       ├── server.py            # MCP 服务器实现
│       ├── api/
│       │   ├── __init__.py
│       │   └── client.py        # Proxmox API 客户端
│       └── tools/
│           ├── vm_tools.py      # 虚拟机管理
│           ├── container_tools_complete.py
│           ├── storage_tools_complete.py
│           ├── ceph_tools.py
│           ├── zfs_tools.py
│           └── ... (15 更多工具模块)
├── tests/
├── pyproject.toml
└── README.md

类型安全性

所有工具都使用严格的 TypedDict 定义：

class VMCreateArgs(TypedDict):
    vmid: int
    node: str
    name: str
    memory: Optional[int]
    cores: Optional[int]
    # ... 无 Dict[str, Any]!

开发

运行测试

pytest tests/
pytest --cov=proxmox_mcp tests/

代码质量

# 格式化代码
black src/

# 类型检查
mypy src/

# 代码检查
ruff src/

贡献

  1. 分叉仓库
  2. 创建功能分支 (git checkout -b feature/new-tool)
  3. 使用 TypedDict 实现（无 Dict[str, Any]）
  4. 添加测试
  5. 提交 (feat: 添加新工具)
  6. 推送并创建 PR

发展路线图

  • 完成所有 115 种工具的实现（✅ 完成！）
  • 动态 ISO 发现和下载（✅ 完成！）
  • 完整的 TypedDict 类型安全性（✅ 完成！）
  • 生产就绪部署（✅ 完成！）
  • 添加全面的测试套件
  • 创建交互式文档
  • 添加工具链能力
  • 实现批处理操作
  • 添加 Prometheus 指标导出
  • 创建 Terraform 提供程序集成

许可证

MIT 许可证 - 详情见 LICENSE 文件。

支持

致谢

  • Proxmox VE 团队提供的优秀虚拟化平台
  • Anthropic 的模型上下文协议规范
  • 所有贡献者和该项目的用户

为 Proxmox 社区打造，充满爱心