MCP Proxmox Admin

MCP Proxmox Admin

Manage Proxmox VE infrastructure through Claude

= 18">

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群集上所有正在运行的虚拟机”

______________________________________________________________________

为什么使用这个？

______________________________________________________________________

可用工具

虚拟机

容器

基础设施

快照

______________________________________________________________________

配置

Claude桌面设置

添加到您的Claude Desktop配置中：

{
  "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"
      }
    }
  }
}

环境变量

配置优先级

1. MCP客户端设置 （最高优先级）
2. 环境变量
3. proxmox-config.json文件 （最低优先级）

______________________________________________________________________

运输方式

在 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代币（推荐）

1. Proxmox用户界面→ 数据中心→ 权限→ API令牌
2. 为您的用户创建令牌
3. 分配 PVEVMAdmin 完全VM控制的角色
4. 将令牌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

1. 验证主机和端口
2. 检查连接： `ping

`

1. 测试API： `curl -k https://

:8006/api2/json`

Authentication failed

1. API令牌格式： user@realm!tokenid
2. 验证令牌未过期
3. 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添加到系统信任存储中

______________________________________________________________________

贡献

欢迎投稿！

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/my-feature
3. 进行更改和测试： npm test
4. 承诺： git commit -m 'Add my feature'
5. 推： git push origin feature/my-feature
6. 打开拉取请求

______________________________________________________________________

许可证

麻省理工学院