Proxmox MCP Enhanced

Proxmox MCP 增强版 🚀

115 通过模型上下文协议实现全面的Proxmox VE管理专用工具

](<>)    

概述

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

特点/功能

🎯 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 支持使用证书验证进行安全通信
• 权限管理细粒度访问控制集成

⚡ 现代建筑

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

安装

通过 pip（Python 包管理工具）

pip install proxmox-mcp-enhanced

来自源头

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

配置

环境变量

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

# Required - Host configuration
PROXMOX_HOST=your-proxmox-host.example.com
PROXMOX_USER=root@pam

# Authentication (choose one method)
# Option 1: API Token (recommended)
PROXMOX_TOKEN_NAME=your-token-name
PROXMOX_TOKEN_VALUE=your-token-value

# Option 2: Password
PROXMOX_PASSWORD=your-password

# Optional settings
PROXMOX_PORT=8006              # Default: 8006
PROXMOX_VERIFY_SSL=true        # Default: 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"
      }
    }
  }
}

使用示例

基本虚拟机操作

# Create a new VM
{
  "tool": "vm_create",
  "arguments": {
    "vmid": 100,
    "node": "pve-node1",
    "name": "test-vm",
    "memory": 2048,
    "cores": 2,
    "storage": "local-lvm",
    "disk_size": "10G"
  }
}

# Start the VM
{
  "tool": "vm_start",
  "arguments": {
    "vmid": 100,
    "node": "pve-node1"
  }
}

容器管理

# Create an LXC container
{
  "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"
  }
}

高级存储操作

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

# Create ZFS dataset
{
  "tool": "zfs_dataset_create",
  "arguments": {
    "name": "tank/datasets/test",
    "pool": "tank",
    "compression": "lz4",
    "dedup": "off"
  }
}

SDN/VXLAN 配置

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

ISO管理（最新）

# Search for OS ISOs dynamically
{
  "tool": "iso_search",
  "arguments": {
    "os_name": "ubuntu",
    "version": "22.04",
    "variant": "server",
    "architecture": "amd64"
  }
}

# Download ISO directly to Proxmox node
{
  "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"
  }
}

# List available ISOs
{
  "tool": "iso_list_available",
  "arguments": {
    "storage": "local"
  }
}

如需完整的ISO下载文档，请参阅 ISO下载指南.md。

自动化与报告生成

# Schedule automated backups
{
  "tool": "schedule_create",
  "arguments": {
    "name": "daily-backup",
    "schedule": "0 2 * * *",
    "command": "backup:all",
    "node": "pve-node1"
  }
}

# Generate performance report
{
  "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          # Tool registration (115 tools)
│       ├── base.py              # Base ToolHandler class
│       ├── types.py             # TypedDict definitions
│       ├── server.py            # MCP server implementation
│       ├── api/
│       │   ├── __init__.py
│       │   └── client.py        # Proxmox API client
│       └── tools/
│           ├── vm_tools.py      # VM management
│           ├── container_tools_complete.py
│           ├── storage_tools_complete.py
│           ├── ceph_tools.py
│           ├── zfs_tools.py
│           └── ... (15 more tool modules)
├── tests/
├── pyproject.toml
└── README.md

类型安全

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

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

发展

运行测试

pytest tests/
pytest --cov=proxmox_mcp tests/

代码质量

# Format code
black src/

# Type checking
mypy src/

# Linting
ruff src/

贡献；做出贡献

1. 为仓库创建分支（或“克隆仓库”）
2. 创建你的特性分支（git checkout -b feature/new-tool)
3. 使用 TypedDict 实现（无需 Dict[str, Any])
4. 添加测试
5. 提交（feat: Add new amazing tool）
6. 推送并创建拉取请求（PR）

路线图

• \[x\] 全部115个工具的完整实现（✅ 完成！)
• \[x\] 动态ISO发现与下载（✅ 已完成！)
• \[x\] 完整的TypedDict类型安全性（✅ 已完成！)
• \[x\] 准备就绪的生产环境部署（✅ 完成！）！)
• \[ \] 添加全面的测试套件
• \[ \] 创建交互式文档
• \[ \] 添加工具链接功能
• \[ \] 实现批量操作
• \[ \] 添加Prometheus指标导出功能
• \[ \] 创建 Terraform 提供者集成

许可证

MIT 许可证 - 详见 许可证 文件中有详细信息。

支持

• 📧 电子邮件：support@proxmox-mcp.dev
• 🐛 问题：
• 💬 Discord（一个即时通讯和视频聊天平台）： 加入我们的服务器
• 📖 文档： 完整文档

致谢

• Proxmox VE团队打造卓越的虚拟化平台
• 针对模型上下文协议规范的人工智能公司（Anthropic）
• 该项目的所有贡献者和用户

______________________________________________________________________

为Proxmox社区倾心打造