AI导哈

Proxmox VE管理服务器

一个通过AI助手管理Proxmox VE基础设施的模型上下文协议(MCP)服务器，支持虚拟机、容器、节点和存储管理。

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

使用说明

Proxmox VE MCP服务器

一个模型上下文协议（MCP）服务器，用于通过人工智能助手（如Claude Desktop、GitHub Copilot、Cursor、Continue和其他兼容MCP的IDE）管理Proxmox VE基础设施。

目录

概述

Proxmox MCP服务器使AI助手能够通过模型上下文协议与您的Proxmox VE基础设施进行交互。这允许您在最喜欢的AI驱动的IDE中使用自然语言命令管理虚拟机、容器、节点和存储。

特性

  • 🖥️ 虚拟机管理：创建、启动、停止、重新启动、克隆和删除虚拟机
  • 📦 容器管理：通过全生命周期控制管理LXC容器
  • 🔧 节点监控：查看群集节点及其资源使用情况
  • 💾 存储管理：列出并监视存储资源
  • 🔐 安全认证：支持API令牌和密码身份验证
  • 🌐 交叉平台的：适用于Linux、Windows和macOS
  • 🔌 多IDE支持：兼容克劳德桌面、VS代码、光标、继续、Zed等
  • 🛡️ 安全第一：输入验证、SSL/TLS支持和无凭据日志记录

快速开始

安装

# Install globally
npm install -g @swartdraak/proxmox-mcp-server

# Or use directly with npx (no installation required)
npx @swartdraak/proxmox-mcp-server

有关详细的安装说明（包括存储库克隆），请参阅 安装.md.

基本配置

为Proxmox连接设置所需的环境变量：

Linux/macOS:

export PROXMOX_HOST="proxmox.example.com"
export PROXMOX_USERNAME="root"
export PROXMOX_TOKEN_ID="your-token-id"
export PROXMOX_TOKEN_SECRET="your-token-secret"

Windows（PowerShell）:

$env:PROXMOX_HOST = "proxmox.example.com"
$env:PROXMOX_USERNAME = "root"
$env:PROXMOX_TOKEN_ID = "your-token-id"
$env:PROXMOX_TOKEN_SECRET = "your-token-secret"

有关完整的配置选项和特定于操作系统的说明，请参阅 安装.md.

IDE集成

在首选IDE或AI助手中配置MCP服务器：

快速示例：克劳德桌面

添加到您的Claude配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "proxmox": {
      "command": "npx",
      "args": ["-y", "@swartdraak/proxmox-mcp-server"],
      "env": {
        "PROXMOX_HOST": "proxmox.example.com",
        "PROXMOX_USERNAME": "root",
        "PROXMOX_TOKEN_ID": "your-token-id",
        "PROXMOX_TOKEN_SECRET": "your-token-secret"
      }
    }
  }
}

有关完整的IDE配置说明，包括VS Code、Cursor、Continue、Cline、Zed等，请参阅 IDE配置.md.

文档

可用工具

虚拟机

  • list_vms -列出所有虚拟机
  • get_vm_status -获取VM状态
  • start_vm -启动虚拟机
  • stop_vm -停止虚拟机（优雅或强制）
  • restart_vm -重新启动虚拟机
  • create_vm -创建新VM
  • delete_vm -删除虚拟机
  • clone_vm -克隆虚拟机
  • get_vm_config -获取VM配置

容器

  • list_containers -列出所有容器
  • get_container_status -获取容器状态
  • start_container -启动容器
  • stop_container -停止容器
  • create_container -创建新容器
  • delete_container -删除容器

节点

  • list_nodes -列出所有群集节点
  • get_node_status -获取节点状态和资源使用情况

存储

  • list_storage -列出所有存储
  • get_storage_status -获取存储内容

认证

Proxmox MCP服务器支持两种身份验证方法。选择最适合您的安全要求的一个：

API代币（推荐）

API令牌更安全，并提供更好的访问控制。它们可以使用特定权限创建，不需要存储您的主密码。

在Proxmox中创建API令牌:

  1. 登录您的Proxmox VE web界面
  2. 导航到 数据中心→ 权限→ API令牌
  3. 点击 添加 创建新令牌
  4. 选择用户（例如。， root@pam)
  5. 输入令牌ID（例如。， mcp-server)
  6. 对于完全用户权限，可以选择取消选中“特权分离”
  7. 点击 添加 并复制显示的秘密（它只显示一次！）

配置:

# Linux/macOS
export PROXMOX_HOST="proxmox.example.com"
export PROXMOX_USERNAME="root"
export PROXMOX_TOKEN_ID="mcp-server"
export PROXMOX_TOKEN_SECRET="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export PROXMOX_REALM="pam"

# Windows PowerShell
$env:PROXMOX_HOST = "proxmox.example.com"
$env:PROXMOX_USERNAME = "root"
$env:PROXMOX_TOKEN_ID = "mcp-server"
$env:PROXMOX_TOKEN_SECRET = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
$env:PROXMOX_REALM = "pam"

密码认证

密码身份验证的设置更简单，但安全性较低。仅在开发环境中或API令牌不可用时使用。

配置:

# Linux/macOS
export PROXMOX_HOST="proxmox.example.com"
export PROXMOX_USERNAME="root"
export PROXMOX_PASSWORD="your-password"
export PROXMOX_REALM="pam"

# Windows PowerShell
$env:PROXMOX_HOST = "proxmox.example.com"
$env:PROXMOX_USERNAME = "root"
$env:PROXMOX_PASSWORD = "your-password"
$env:PROXMOX_REALM = "pam"

可选配置

用于微调的其他环境变量：

# Proxmox API port (default: 8006)
export PROXMOX_PORT="8006"

# Realm (default: pam)
export PROXMOX_REALM="pam"

# SSL/TLS verification (default: true)
# Set to false only for self-signed certificates in development
export PROXMOX_VERIFY_SSL="true"

# Request timeout in milliseconds (default: 30000)
export PROXMOX_TIMEOUT="30000"

发展

从源头构建

# Clone the repository
git clone https://github.com/Swartdraak/Proxmox-MCP.git
cd Proxmox-MCP

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Run the server
npm start

开发流程

# Watch mode (automatically rebuilds on changes)
npm run watch

# Type checking without building
npm run lint

# Clean build artifacts
npm run clean

# Clean and rebuild
npm run clean && npm run build

项目结构

src/
└── index.ts              # Main server entry point

测试

# This project does not yet include automated tests.
# Running the default test script will simply report that no tests are defined:
npm test

贡献

我们欢迎捐款！请参阅 贡献.md 用于：

  • 行为准则
  • 开发设置
  • 编码标准
  • 拉取请求流程
  • 安全指南

支持

获取帮助

报告问题

在报告问题时，请包括：

  • 操作系统和版本
  • Node.js版本(node --version)
  • 安装方法（npm、npx或存储库克隆）
  • IDE和版本
  • 完整的错误消息和日志
  • 重现问题的步骤

安全

Proxmox MCP服务器的构建将安全性作为首要任务：

  • 输入验证：所有输入都使用标准的TypeScript检查进行验证和净化
  • TLS/SSL支持：完全支持SSL/TLS证书验证
  • 安全凭据：凭据从不被记录或公开
  • 最小API表面：仅暴露基本的Proxmox API终结点
  • API代币支持：推荐使用细粒度权限的身份验证方法
  • 无凭据存储：凭据仅通过环境变量传递

安全最佳实践

  1. 使用API令牌：首选API令牌而不是密码身份验证
  2. 限制权限：仅使用必要的权限创建令牌
  3. 启用SSL/TLS：始终使用 PROXMOX_VERIFY_SSL=true 生产中
  4. 安全环境变量：使用安全方法存储环境变量
  5. 定期更新：保持MCP服务器更新以获取安全补丁
  6. 网络安全：确保Proxmox API不会暴露于不受信任的网络
  7. 审核访问权限：定期查看Proxmox审核日志，查看是否存在未经授权的访问
  8. 速率限制：部署在反向代理或API网关（例如nginx、Caddy）后面，强制执行适合您环境的速率限制

故障排除

常见问题

问题：无法连接到Proxmox服务器

解决方案:

  • 验证 PROXMOX_HOST 正确且可访问
  • 检查端口8006（或您的自定义端口）是否打开
  • 确保防火墙允许来自您计算机的连接
  • 尝试设置 PROXMOX_VERIFY_SSL=false 用于自签名证书（仅用于开发）

问题：身份验证失败

解决方案:

  • 验证您的API令牌或密码是否正确
  • 检查令牌是否未过期
  • 确保用户有足够的权限
  • 验证 PROXMOX_REALM 设置正确（通常为“pam”或“pve”）

问题：工具未出现在IDE中

解决方案:

  • 配置更改后重新启动IDE
  • 检查IDE的MCP服务器日志是否有错误
  • 验证配置文件语法是否为有效的JSON
  • 确保设置了所有必需的环境变量

问题：权限被拒绝错误

解决方案:

  • 请检查您的API令牌或用户是否具有所需的权限
  • 查看用户的Proxmox角色分配
  • 如果需要完全访问权限，请确保创建的令牌没有“特权分离”

有关更详细的故障排除，请参阅：

贡献

欢迎投稿！无论您是在修复错误、添加功能还是改进文档，我们都感谢您的帮助。

如何做出贡献

  1. 克隆该仓库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 进行更改
  4. 运行测试和梳理(npm run lint)
  5. 提交您的更改(git commit -m 'feat: add amazing feature')
  6. 推到分支(git push origin feature/amazing-feature)
  7. 打开拉取请求

看 贡献.md 详细指南。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

相关项目

由...制作❤️ 面向Proxmox和AI社区

相关 MCP