使用说明

Proxmox MCP服务器

一个模型上下文协议（MCP）服务器，使Claude能够管理Proxmox VE基础设施——VM、LXC容器、快照、存储等。

特性

节点管理 --列出集群节点，监控CPU/RAM/磁盘指标
VM和容器控制 --启动、停止、重启、销毁QEMU虚拟机和LXC容器
快照 --创建、列出、删除和回滚快照
存储 --浏览存储池和内容（ISO、备份、模板）
任务监控 --实时跟踪Proxmox任务
SSH访问 --直接在Proxmox主机上执行命令
用户管理 --创建、更新、删除Proxmox用户
客户代理 --通过QEMU Guest Agent在VM内执行命令
Docker就绪 --以最小配置作为容器运行

Docker Compose快速入门

步骤1：克隆存储库

git clone https://github.com/BenjaminDuthe/proxmox-mcp.git
cd proxmox-mcp

步骤2：创建配置文件

cp .env.example .env

步骤3：编辑 `.env` 使用您的Proxmox凭据

打开 .env 在编辑器中，替换占位符值：

# ⚠️ REQUIRED - Replace these values with your own

PROXMOX_HOST=<YOUR_PROXMOX_IP>           # Example: 192.168.1.10
PROXMOX_PORT=8006                         # Default Proxmox port (usually no change needed)

PROXMOX_TOKEN_ID=<YOUR_TOKEN_ID>          # Example: root@pam!mcp
PROXMOX_TOKEN_SECRET=<YOUR_TOKEN_SECRET>  # Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

PROXMOX_VERIFY_SSL=false                  # Set to 'true' if you have valid SSL certificates
PROXMOX_TIMEOUT=30

# 📌 OPTIONAL - For SSH access to Proxmox host

PROXMOX_SSH_USER=root
PROXMOX_SSH_KEY_PATH=<PATH_TO_YOUR_SSH_KEY>  # Example: ~/.ssh/id_rsa

📋 传说：

<YOUR_PROXMOX_IP> → 您的Proxmox服务器IP地址（例如。， 192.168.1.10)

<YOUR_TOKEN_ID> → 在Proxmox中创建的API令牌ID（例如。， root@pam!mytoken)

<YOUR_TOKEN_SECRET> → 创建令牌时显示的秘密（UUID格式）

<PATH_TO_YOUR_SSH_KEY> → SSH私钥的路径（可选，适用于SSH工具）

步骤4：生成SSH密钥（可选，适用于SSH工具）

如果你想使用SSH工具(ssh_execute, ssh_read_file等等）：

# Generate a dedicated SSH key
ssh-keygen -t ed25519 -f ~/.ssh/id_proxmox_mcp -N "" -C "proxmox-mcp"

# Copy the public key to your Proxmox server
ssh-copy-id -i ~/.ssh/id_proxmox_mcp.pub root@<YOUR_PROXMOX_IP>

然后更新 .env:

PROXMOX_SSH_KEY_PATH=~/.ssh/id_proxmox_mcp

第五步：从Docker Compose开始

docker compose up -d

发生了什么：

Docker构建 proxmox-mcp Dockerfile中的图像
容器以您的 .env 配置
SSH密钥在容器内以只读方式挂载
MCP服务器已准备好接收命令

步骤6：检查它是否正在运行

# View logs
docker compose logs

# Expected output:
# proxmox-mcp  | INFO - Configuration loaded: 192.168.1.10:8006
# proxmox-mcp  | INFO - Proxmox client connected
# proxmox-mcp  | INFO - MCP server ready

步骤7：停止/重新启动

# Stop
docker compose down

# Restart (after .env changes)
docker compose up -d --force-recreate

# Rebuild (after code changes)
docker compose up -d --build

Docker编写文件详解

这 docker-compose.yml 文件：

services:
  proxmox-mcp:
    build: .                    # Build image from local Dockerfile
    image: proxmox-mcp:latest   # Image name
    container_name: proxmox-mcp # Container name

    stdin_open: true            # Keep STDIN open (required for MCP protocol)
    tty: true                   # Allocate pseudo-TTY

    env_file:
      - .env                    # Load environment variables from .env file

    environment:
      # Override SSH key path for container filesystem
      - PROXMOX_SSH_KEY_PATH=/home/mcp/.ssh/id_proxmox_mcp

    volumes:
      # Mount your SSH key inside the container (read-only)
      - ~/.ssh/id_proxmox_mcp:/home/mcp/.ssh/id_proxmox_mcp:ro

    restart: unless-stopped     # Auto-restart on failure

要点：

stdin_open + tty 是必需的，因为MCP使用stdio进行通信
.env 文件是自动加载的（从不提交到git）
SSH密钥安装在 /home/mcp/.ssh/ （容器以非根目录运行 mcp 用户）
:ro 意味着只读（安全最佳实践）

替代方案：使用Docker运行（不使用Compose）

# Build the image
docker build -t proxmox-mcp .

# Run with .env file
docker run --rm -it --env-file .env proxmox-mcp

# Run with SSH key mounted
docker run --rm -it \
  --env-file .env \
  -e PROXMOX_SSH_KEY_PATH=/home/mcp/.ssh/id_proxmox_mcp \
  -v ~/.ssh/id_proxmox_mcp:/home/mcp/.ssh/id_proxmox_mcp:ro \
  proxmox-mcp

替代方案：本地安装（无Docker）

# Install Python package
pip install -e ".[dev]"

# Run MCP server
python -m proxmox_mcp.server

配置参考

环境变量

变量	描述	必填	默认
`PROXMOX_HOST`	Proxmox服务器IP或主机名	是	—
`PROXMOX_PORT`	API端口	否	`8006`
`PROXMOX_TOKEN_ID`	API令牌ID(`user@realm!token`)	是*	—
`PROXMOX_TOKEN_SECRET`	API令牌机密（UUID）	是*	—
`PROXMOX_USER`	用户名（替代令牌）	是*	—
`PROXMOX_PASSWORD`	密码（替代令牌）	是*	—
`PROXMOX_VERIFY_SSL`	验证SSL证书	否	`false`
`PROXMOX_TIMEOUT`	请求超时（秒）	否	`30`
`PROXMOX_SSH_KEY_PATH`	SSH私钥路径	否	--
`PROXMOX_SSH_USER`	SSH用户名	否	`root`

* 要么 TOKEN_ID + TOKEN_SECRET 或 USER + PASSWORD 是必需的。建议使用Token。

在Proxmox中创建API令牌

打开Proxmox web界面(https://your-proxmox:8006)
首选 数据中心 → 权限 → API令牌
点击添加
填写：
- 用户: root@pam （或您的用户）
- 令牌ID: mcp （或任何你想要的名字）
- 特权分离: ⚠️ 取消选中此项 继承用户权限
点击添加
立即复制令牌密钥 （只显示一次！）

您的令牌ID将是： root@pam!mcp

Claude桌面配置

选项1：使用Docker（推荐）

添加到您的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": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "<PATH_TO_PROJECT>/.env",
        "-e", "PROXMOX_SSH_KEY_PATH=/home/mcp/.ssh/id_proxmox_mcp",
        "-v", "<PATH_TO_SSH_KEY>:/home/mcp/.ssh/id_proxmox_mcp:ro",
        "proxmox-mcp"
      ]
    }
  }
}

替换：

<PATH_TO_PROJECT> → 克隆存储库的完整路径（例如。， /home/user/proxmox-mcp)

<PATH_TO_SSH_KEY> → SSH私钥的完整路径（例如。， /home/user/.ssh/id_proxmox_mcp)

选项2：使用Python（本地安装）

{
  "mcpServers": {
    "proxmox": {
      "command": "python",
      "args": ["-m", "proxmox_mcp.server"],
      "cwd": "<PATH_TO_PROJECT>",
      "env": {
        "PROXMOX_HOST": "<YOUR_PROXMOX_IP>",
        "PROXMOX_TOKEN_ID": "<YOUR_TOKEN_ID>",
        "PROXMOX_TOKEN_SECRET": "<YOUR_TOKEN_SECRET>",
        "PROXMOX_VERIFY_SSL": "false"
      }
    }
  }
}

替换：

<PATH_TO_PROJECT> → 克隆存储库的完整路径

<YOUR_PROXMOX_IP> → 您的Proxmox服务器IP

<YOUR_TOKEN_ID> → 您的API令牌ID（例如。， root@pam!mcp)

<YOUR_TOKEN_SECRET> → 您的API令牌机密

可用工具

节点

工具	说明
`list_nodes`	列出所有具有CPU/RAM/磁盘指标的群集节点
`get_node_status`	获取特定节点的详细状态

虚拟机（QEMU）

工具	说明
`list_vms`	列出所有VM的状态和资源使用情况
`get_vm_details`	获取完整的VM配置
`start_vm`	启动虚拟机
`stop_vm`	强制停止虚拟机
`shutdown_vm`	优雅关机（ACPI）
`reboot_vm`	重新启动虚拟机
`destroy_vm`	永久删除 VM及其磁盘

集装箱（LXC）

工具	说明
`list_containers`	列出所有LXC容器
`get_container_details`	获取完整容器配置

LXC容器支持与VM相同的启动/停止/关闭/重新启动/销毁操作。

快照

工具	说明
`list_snapshots`	列出VM/容器的快照
`create_snapshot`	创建新快照
`delete_snapshot`	删除快照
`rollback_snapshot`	将VM/容器还原到快照

存储

工具	说明
`list_storage`	列出具有使用情况统计信息的存储池
`get_storage_content`	列出内容（ISO、备份、映像）

任务

工具	说明
`list_tasks`	列出最近的Proxmox任务
`get_task_status`	通过UPID获取详细的任务状态

SSH（Proxmox主机）

工具	说明
`ssh_execute`	在Proxmox主机上执行命令
`ssh_read_file`	从Proxmox主机读取文件
`ssh_write_file`	将文件写入Proxmox主机
`fix_apt_repos`	修复非订阅的APT存储库

用户

工具	说明
`list_users`	列出所有Proxmox用户
`get_user`	获取用户详细信息和令牌
`create_user`	创建新用户
`update_user`	更新用户属性
`delete_user`	删除用户

客户代理（VM）

工具	说明
`vm_exec`	在VM内执行命令
`vm_exec_status`	获取异步命令结果
`vm_exec_sync`	执行命令并等待结果
`vm_file_read`	从VM内部读取文件
`vm_file_write`	在VM内写入文件（受保护的路径）

故障排除

“连接被拒绝”错误

检查一下 PROXMOX_HOST 是正确的
验证Proxmox API是否可访问： curl -k https://<YOUR_PROXMOX_IP>:8006/api2/json
检查Proxmox上的防火墙规则

“身份验证失败”错误

验证 PROXMOX_TOKEN_ID 格式： user@realm!tokenname （例如。， root@pam!mcp)
检查令牌密钥是否正确（无多余空格）
确保“特权分离” 未受抑制的 在令牌上

SSH工具不工作

检查SSH密钥路径是否正确 .env
验证Proxmox上的密钥是否已授权： ssh -i ~/.ssh/id_proxmox_mcp root@<YOUR_PROXMOX_IP>
在Docker中，确保卷挂载路径匹配 PROXMOX_SSH_KEY_PATH

Docker：SSH密钥上的“权限被拒绝”

确保SSH密钥文件具有正确的权限： chmod 600 ~/.ssh/id_proxmox_mcp
容器运行方式如下 mcp 用户（UID 1000）

建筑

src/proxmox_mcp/
├── server.py          # MCP server entry point
├── client.py          # Async Proxmox API client (httpx)
├── ssh_client.py      # Async SSH client (asyncssh)
├── config.py          # Environment-based configuration
├── models.py          # Pydantic models
├── exceptions.py      # Custom exceptions
└── tools/             # Tool implementations
    ├── nodes.py
    ├── vms.py
    ├── containers.py
    ├── snapshots.py
    ├── storage.py
    ├── tasks.py
    ├── ssh.py
    └── users.py

发展

安装开发依赖项

pip install -e ".[dev]"

运行测试

pytest -v --cov=proxmox_mcp

棉绒和格式

ruff check src/
ruff format src/

安全说明

永不承诺 .env --它包含敏感凭据
使用API令牌 --更喜欢令牌而不是用户/密码
限制令牌权限 --创建具有最低所需权限的专用令牌
受保护的路径 — vm_file_write 阻止写入敏感文件(/etc/shadow, /etc/passwd等等）

贡献

欢迎投稿！请随时提交拉取请求。

克隆该仓库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

许可证

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

致谢

Proxmox VE --强大的开源虚拟化平台
模型上下文协议 --人工智能工具集成的Anthropic协议
克劳德 --人工智能助手Anthropic