Skip to main content
Glama
deenesjakoruzh
akmalovaa

proxmox-mcp

by akmalovaa
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

Proxmox-mcp

CI Release License: MIT Python 3.14 GHCR MCP

简单的 Proxmox MCP

用于管理 Proxmox VE 的 MCP 服务器

38 个工具 — 涵盖节点、QEMU 虚拟机、LXC 容器、存储、集群和快照。

为什么选择这个？

  • 单一镜像，多架构支持 — docker run ghcr.io/akmalovaa/proxmox-mcp:latest 即可完成部署

  • 仅需环境变量 — 无需配置文件，无需数据库，无状态

  • 默认只读 — 破坏性操作受 PROXMOX_RISK_LEVEL 显式控制

  • 代码库极小 — 基于 Proxmoxer 的纯 stdio MCP，无 HTTP 服务器，无认证层，无冗余功能

  • 原始 JSON 输出 — 无格式化，无表情符号；LLM 可获取纯净数据

快速开始

镜像： ghcr.io/akmalovaa/proxmox-mcp:latest (多架构：amd64 + arm64)。

1. 在 shell 配置文件中导出凭据 (~/.zprofile, ~/.zshrc 或 ~/.bashrc)：

# base environment:
export PROXMOX_HOST=192.168.1.100
export PROXMOX_USER=root@pam
export PROXMOX_PASSWORD=your-password

# or use token auth (recommended):
export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# optional:
export PROXMOX_RISK_LEVEL=read

重新加载：source ~/.zprofile (或重启 shell)。

2. 添加到 ~/.claude/settings.json (Claude Code) 或 claude_desktop_config.json (Claude Desktop)：

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PROXMOX_HOST",
        "-e", "PROXMOX_USER",
        "-e", "PROXMOX_PASSWORD",
        "ghcr.io/akmalovaa/proxmox-mcp:latest"]
    }
  }
}

或者使用令牌认证：

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PROXMOX_HOST",
        "-e", "PROXMOX_USER",
        "-e", "PROXMOX_TOKEN_NAME",
        "-e", "PROXMOX_TOKEN_VALUE",
        "ghcr.io/akmalovaa/proxmox-mcp:latest"]
    }
  }
}

docker run -e VAR 若不带值，则会透传宿主机变量 — 配置文件中不会出现密钥。重启客户端 — 38 个 Proxmox 工具即可使用。

对于密码认证，将令牌变量替换为 PROXMOX_PASSWORD。

注意： macOS 上的 Claude Desktop 通过 launchd 启动，不继承 ~/.zprofile/~/.zshrc。请将导出语句放入 ~/.zshenv，或者在配置中使用内联的 "env": { ... } 块。

配置

所有设置均为环境变量 — 在 shell 配置文件中设置，通过 docker run -e 内联传递，或在 MCP 客户端的 env 块中声明。

变量

默认值

描述

PROXMOX_HOST

—

Proxmox 主机 (IP 或主机名)

PROXMOX_USER

root@pam

API 用户

认证

—

PROXMOX_PORT

8006

API 端口

PROXMOX_VERIFY_SSL

false

验证 TLS 证书

PROXMOX_RISK_LEVEL

read

read / lifecycle / all

认证：令牌 或 密码

选择一种。如果两者都设置，则令牌优先。

令牌 (推荐) — 在 Proxmox UI 中创建：数据中心 → 权限 → API 令牌 → 添加 (取消勾选 权限分离)。然后：

export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

密码 (备选)：

export PROXMOX_PASSWORD=your-password

风险等级

PROXMOX_RISK_LEVEL 控制破坏性操作：

等级

添加功能

read (默认)

只读工具

lifecycle

+ 启动 / 停止 / 重启 / 挂起 / 克隆 / 创建快照

all

+ 删除快照 / 回滚快照

每次高权限调用都会记录到 stderr (ALLOW / DENY + 工具 + 等级)。

工具

节点 (7)

工具

描述

list_nodes

列出所有集群节点及其状态、CPU、内存、运行时间

get_node_status

详细的节点指标 (CPU、内存、磁盘、负载、内核)

get_node_networks

节点上的网络接口

get_node_disks

节点上的物理磁盘

get_node_tasks

节点上的近期任务

get_task_status

通过 UPID 获取特定任务的状态

get_task_log

任务的日志输出

QEMU 虚拟机 (14)

工具

等级

描述

list_vms

read

列出所有虚拟机，可选按节点过滤

get_vm_status

read

当前虚拟机状态 (运行/停止、CPU、内存)

get_vm_config

read

虚拟机配置 (硬件、磁盘、网络)

list_vm_snapshots

read

列出虚拟机的所有快照

start_vm

lifecycle

启动虚拟机

stop_vm

lifecycle

强制停止虚拟机

shutdown_vm

lifecycle

带超时的优雅 ACPI 关机

reboot_vm

lifecycle

通过 ACPI 重启

suspend_vm

lifecycle

挂起虚拟机

resume_vm

lifecycle

恢复挂起的虚拟机

clone_vm

lifecycle

完整或链接克隆

create_vm_snapshot

lifecycle

创建快照

delete_vm_snapshot

all

删除快照

rollback_vm_snapshot

all

回滚到快照

LXC 容器 (11)

工具

等级

描述

list_containers

read

列出所有 LXC 容器，可选按节点过滤

get_container_status

read

当前容器状态

get_container_config

read

容器配置

list_container_snapshots

read

列出所有快照

start_container

lifecycle

启动容器

stop_container

lifecycle

强制停止容器

shutdown_container

lifecycle

带超时的优雅关机

reboot_container

lifecycle

重启容器

create_container_snapshot

lifecycle

创建快照

delete_container_snapshot

all

删除快照

rollback_container_snapshot

all

回滚到快照

存储 (2)

工具

描述

list_storage

存储池及其使用情况，可选按节点过滤

get_storage_content

存储池内容 (ISO、备份、镜像、模板)

集群 (4)

工具

描述

get_cluster_status

集群健康状况、仲裁、节点成员资格

get_cluster_resources

所有资源 (虚拟机、容器、存储、节点)

get_cluster_backups

已配置的备份任务

get_next_vmid

下一个可用的虚拟机/容器 ID

架构

src/proxmox_mcp/
├── server.py    # FastMCP instance + entry point
├── config.py    # Pydantic Settings (PROXMOX_ prefix)
├── client.py    # Proxmoxer connection via lifespan
└── tools/       # nodes, vms, containers, storage, cluster

  • 默认只读 — 高权限工具受 PROXMOX_RISK_LEVEL 控制

  • 单一连接 — Proxmoxer 客户端在启动时创建一次，通过生命周期共享

  • 原始 JSON 输出 — 无格式化；LLM 直接处理数据

开发

独立运行 (测试)

export PROXMOX_HOST=192.168.1.100
export PROXMOX_USER=root@pam
export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

docker run -i --rm \
  -e PROXMOX_HOST -e PROXMOX_USER \
  -e PROXMOX_TOKEN_NAME -e PROXMOX_TOKEN_VALUE \
  ghcr.io/akmalovaa/proxmox-mcp:latest

不使用 Docker (UV)

git clone https://github.com/akmalovaa/proxmox-mcp.git && cd proxmox-mcp && uv sync

MCP 客户端配置：

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/proxmox-mcp", "proxmox-mcp"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_TOKEN_NAME": "mcp",
        "PROXMOX_TOKEN_VALUE": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

从源码构建

git clone https://github.com/akmalovaa/proxmox-mcp.git
cd proxmox-mcp
docker build -t proxmox-mcp .

许可证

MIT

Install Server
A
license - permissive license
A
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
0dRelease cycle
6Releases (12mo)

Resources

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/akmalovaa/proxmox-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server