使用说明
MCP Proxmox Admin
Manage Proxmox VE infrastructure through Claude
Quick Start | Tools | Configuration | Contributing
这是什么？
MCP（模型上下文协议）服务器，使Claude能够管理您的Proxmox VE基础设施。通过自然语言控制VM、容器、快照和监控集群健康状况。
适用于Claude Desktop、Cursor和任何兼容MCP的客户端。
快速开始
# Install globally
npm install -g mcp-proxmox-admin
# Or run directly with npx
npx mcp-proxmox-admin
添加到Claude Desktop配置并开始管理Proxmox集群：
“显示Proxmox群集上所有正在运行的虚拟机”
为什么使用这个？
| 特性 | 描述 |
|---|---|
| 完全VM控制 | 启动、停止、关闭、重新启动虚拟机 |
| 容器管理 | 同样轻松地管理LXC容器 |
| 快照操作 | 创建、还原和删除快照 |
| 混合运输 | 根据操作自动选择SSH或REST API |
| 安全模式 | 可选的只读监控模式 |
可用工具
虚拟机
| 工具 | 说明 |
|---|---|
proxmox_vm_list |
列出跨节点的所有虚拟机 |
proxmox_vm_start |
启动虚拟机 |
proxmox_vm_stop |
立即停止VM |
proxmox_vm_shutdown |
优雅的ACPI关闭 |
proxmox_vm_restart |
重新启动虚拟机 |
容器
| 工具 | 说明 |
|---|---|
proxmox_ct_list |
列出所有LXC容器 |
proxmox_ct_start |
启动容器 |
proxmox_ct_stop |
停止容器 |
proxmox_ct_restart |
重新启动容器 |
基础设施
| 工具 | 说明 |
|---|---|
proxmox_node_list |
列出群集节点 |
proxmox_node_status |
获取节点CPU、内存、磁盘 |
proxmox_storage_list |
列出存储池 |
快照
| 工具 | 说明 |
|---|---|
proxmox_snapshot_list |
列出VM/容器的快照 |
proxmox_snapshot_create |
创建新快照 |
proxmox_snapshot_restore |
还原到快照 |
proxmox_snapshot_delete |
删除快照（需要确认） |
配置
Claude桌面设置
添加到您的Claude Desktop配置中：
| 平台 | 配置路径 |
|---|---|
| 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": ["mcp-proxmox-admin"],
"env": {
"PROXMOX_HOST": "192.168.1.100",
"PROXMOX_API_TOKEN_ID": "user@pam!mytoken",
"PROXMOX_API_TOKEN_SECRET": "your-secret-here",
"PROXMOX_SSH_USER": "root",
"PROXMOX_SSH_KEY_PATH": "~/.ssh/id_rsa"
}
}
}
}
环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
PROXMOX_HOST |
Proxmox主机/IP | 必需的 |
PROXMOX_PORT |
API端口 | 8006 |
PROXMOX_API_TOKEN_ID |
API令牌（格式： user@realm!tokenid) |
|
PROXMOX_API_TOKEN_SECRET |
API令牌机密 | |
PROXMOX_VERIFY_SSL |
验证SSL证书 | true |
PROXMOX_SSH_USER |
SSH用户名 | |
PROXMOX_SSH_PORT |
SSH端口 | 22 |
PROXMOX_SSH_KEY_PATH |
SSH私钥路径 | |
PROXMOX_SSH_PASSWORD |
SSH密码（密钥的替代） | |
PROXMOX_DEFAULT_TRANSPORT |
ssh, api，或 auto |
auto |
PROXMOX_DEFAULT_NODE |
默认节点名称 | |
PROXMOX_TIMEOUT |
请求超时（ms） | 30000 |
PROXMOX_SAFE_MODE |
禁用破坏性操作 | false |
配置优先级
- MCP客户端设置 （最高优先级）
- 环境变量
- proxmox-config.json文件 （最低优先级）
运输方式
| 模式 | 描述 |
|---|---|
auto |
每次操作的最佳运输（推荐） |
api |
仅限REST API |
ssh |
仅限SSH命令 |
在 auto 模式：API用于读取，SSH用于快照和配置更改。
例子
VM Management
"Show me all running VMs"
"Start VM 100 on node pve"
"Gracefully shutdown VM 101"
"Stop VM 102 immediately"
Container Management
"List all LXC containers"
"Start container 200"
"Restart container 201"
Snapshots
"Create a snapshot of VM 100 named 'before-upgrade'"
"List snapshots for VM 100"
"Restore VM 100 to snapshot 'before-upgrade'"
"Delete snapshot 'old-backup' from VM 100"
Cluster Monitoring
"What's the status of node pve?"
"Show me CPU and memory usage for all nodes"
"List all storage pools and available space"
认证
API代币（推荐）
- Proxmox用户界面→ 数据中心→ 权限→ API令牌
- 为您的用户创建令牌
- 分配
PVEVMAdmin完全VM控制的角色 - 将令牌ID和密钥添加到配置中
SSH密钥
# Generate key if needed
ssh-keygen -t ed25519
# Copy to Proxmox
ssh-copy-id root@proxmox-host
安全模式
启用只读监视：
PROXMOX_SAFE_MODE=true
禁用：快照删除和其他破坏性操作。
发展
# Clone
git clone https://github.com/EricGrill/mcp-proxmox-admin.git
cd mcp-proxmox-admin
# Install & build
npm install
npm run build
# Test
npm test
# Dev mode (watch)
npm run dev
故障排除
Cannot connect to Proxmox
- 验证主机和端口
- 检查连接：
ping <proxmox-host> - 测试API：
curl -k https://<proxmox-host>:8006/api2/json
Authentication failed
- API令牌格式：
user@realm!tokenid - 验证令牌未过期
- SSH密钥权限：
chmod 600 ~/.ssh/id_rsa
Permission denied
所需的Proxmox权限：
VM.PowerMgmt-启动/停止/重新启动VM.Snapshot-快照操作Sys.Audit-节点/存储信息
SSL certificate errors
对于自签名证书：
- 集
PROXMOX_VERIFY_SSL=false（仅限dev） - 或者将Proxmox CA添加到系统信任存储中
贡献
欢迎投稿！
- 分叉存储库
- 创建要素分支：
git checkout -b feature/my-feature - 进行更改和测试：
npm test - 承诺：
git commit -m 'Add my feature' - 推：
git push origin feature/my-feature - 打开拉取请求
许可证
麻省理工学院