使用说明

Proxmox MCP服务器

⚠️ 存储库已移动

此存储库已移动到： husniadil/mcp远程执行器

请使用新存储库获取最新更新和功能。

使用自然语言直接从Claude AI控制Proxmox LXC容器。

⚠️ 免责声明/罚款

英语：

使用风险自负。 该软件在Proxmox基础架构上提供直接SSH访问和命令执行功能。此软件的开发人员是 不负责任 对于使用此软件可能引起的任何损坏、数据丢失、系统故障、安全漏洞或任何其他问题。

通过使用此软件，您承认：

您了解让AI系统SSH访问您的基础设施的风险
您全权负责在执行之前审查和批准命令
您有适当的备份和灾难恢复程序
您不会要求开发商对任何损害或损失承担责任

印度尼西亚：

使用风险由您自己承担。 该软件为您的Proxmox基础设施提供直接SSH访问和命令执行功能。该软件的开发者 不负责任 因使用本软件而导致的损坏、数据丢失、系统故障、安全漏洞或其他问题。

通过使用本软件，您声明：

您了解向您的基础设施提供 AI 系统 SSH 访问的风险
您有责任在执行前检查和批准订单。
你有足够的备份和灾难恢复程序
您不会要求开发者对任何损坏或损失承担责任

本软件按“原样”提供，不提供任何形式的明示或暗示担保。

✅ 强制风险接受

要使用此软件，您必须设置环境变量：

I_ACCEPT_RISKS=true

软件将 拒绝开始 没有明确的承认。这确保您在让AI系统SSH访问您的基础设施之前，已经阅读并理解了风险。

这是什么？

此MCP（模型上下文协议）服务器允许您使用自然语言通过Claude Desktop管理Proxmox容器。不要在服务器中键入命令，只需问Claude：

“检查容器100上的磁盘空间”

“更新容器101上的包”

“显示容器102中的nginx日志”

Claude将执行命令并向您显示结果。

特性

✅ 执行bash命令 集装箱内部
✅ 管理容器 -启动、停止、检查状态
✅ 列出所有容器 与他们目前的状态
✅ 自然语言界面 -无需记住命令
✅ 安全 -使用带有密钥或密码身份验证的SSH
✅ 现代 -使用PEP 723（不需要requirements.txt）

快速开始

先决条件

带LXC容器的Proxmox VE
SSH访问您的Proxmox主机
已安装Claude Desktop
Python 3.10或更高版本

安装

选项A：使用 uv （推荐）

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/husniadil/proxmox-mcp-server.git
cd proxmox-mcp-server

# Configure your Proxmox connection
cp .env.example .env
nano .env  # Add your Proxmox host details

# Test it works
uv run proxmox_mcp.py

选项B：传统Python

# Clone the repository
git clone https://github.com/husniadil/proxmox-mcp-server.git
cd proxmox-mcp-server

# Install dependencies
pip install mcp fastmcp paramiko pydantic python-dotenv uvicorn

# Configure your Proxmox connection
cp .env.example .env
nano .env  # Add your Proxmox host details

# Test it works
python proxmox_mcp.py

选项C:带HTTP传输的Docker

安全警告： HTTP模式不包括任何身份验证机制。服务器完全依赖于您的.env文件凭据来访问Proxmox，但HTTP端点本身未经身份验证。这意味着任何可以访问HTTP端点的人都可以在Proxmox基础架构上执行命令。

建议的安全措施：

仅在本地主机（127.0.0.1）或受信任的网络上公开服务器
使用防火墙限制对HTTP端口的访问
考虑使用带有身份验证的反向代理（nginx、Caddy等）
使用VPN或SSH隧道进行远程访问
永远不要将HTTP端点直接暴露给互联网
保护.env文件的安全，永远不要将其提交给版本控制

将MCP服务器托管为web服务（使用HTTP/Streamable HTTP）而不是本地子进程：

# Clone the repository
git clone https://github.com/husniadil/proxmox-mcp-server.git
cd proxmox-mcp-server

# Configure your Proxmox connection
cp .env.example .env
nano .env  # Add your Proxmox host details

# Build and run with Docker Compose
docker-compose up -d

# Check logs
docker-compose logs -f

# Stop the server
docker-compose down

或者直接使用Docker：

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

# Run the container
docker run -d \
  --name proxmox-mcp \
  -p 8000:8000 \
  --env-file .env \
  proxmox-mcp-server

# Check logs
docker logs -f proxmox-mcp

# Stop the container
docker stop proxmox-mcp
docker rm proxmox-mcp

重要提示： 环境变量在运行时传递（不烘焙到映像中），因此构建的映像可以安全地推送到Docker注册表。仅当容器以以下方式运行时，才会加载凭据 --env-file .env 或者通过docker compose。

服务器将在以下时间可用 http://localhost:8000/mcp 使用HTTP传输。这有助于：

远程访问MCP服务器
在生产环境中运行
与web应用程序集成
在集装箱化基础设施中部署

注： FastMCP 2.x使用HTTP传输（流式HTTP），而不是弃用的SSE传输。

Docker部署详细信息

环境变量：

您可以使用您的 .env 文件或Docker Compose环境部分：

environment:
  - I_ACCEPT_RISKS=true
  - HOST=192.168.1.100
  - SSH_USERNAME=root
  - SSH_PASSWORD=your_password
  - ENABLE_HOST_EXEC=false
  - CHARACTER_LIMIT=25000
  - MAX_FILE_SIZE=10485760
  - SERVER_PORT=8000

使用Docker Secrets（生产）：

为了提高生产中的安全性，请使用Docker secrets：

# Create secret files
echo "your_password" > ./secrets/ssh_password.txt

# Update docker-compose.yml to use secrets
# See docker-compose.yml for secret configuration examples

自定义端口：

要使用其他端口，请设置 SERVER_PORT 环境变量：

# Option 1: Using environment variable (recommended)
# In your .env or stack.env file:
SERVER_PORT=9000

# The docker-compose.yml will automatically use this port
docker-compose up -d

# Option 2: Using Docker directly
docker run -d -p 9000:9000 -e SERVER_PORT=9000 --env-file .env proxmox-mcp-server

# Option 3: Command line argument (overrides env var)
docker run -d -p 9000:9000 --env-file .env proxmox-mcp-server --http --port 9000

注：更改时 SERVER_PORT，确保更新Docker端口映射中的主机和容器端口以匹配。

健康检查：

Docker容器在以下位置包含一个健康检查端点 /health 返回服务器状态和SSH连接状态：

# Check container health
docker ps  # Look for "(healthy)" status

# Manual health check
curl http://localhost:8000/health

健康端点返回JSON响应：

{
  "status": "healthy",
  "service": "proxmox-mcp-server",
  "ssh_connected": true
}

status：如果服务器正在运行，则始终“健康”
service：服务标识符
ssh_connected: true 如果建立了到Proxmox的SSH连接， false 否则

正在连接到HTTP服务器：

要将应用程序连接到HTTP服务器，请执行以下操作：

# Example: Connect to MCP server via HTTP
import requests

# Health check
response = requests.get('http://localhost:8000/health')
print(response.text)

# MCP endpoint (for MCP clients)
# Use MCP client libraries to connect to http://localhost:8000/mcp

对于MCP客户端连接：

from mcp import Client

async with Client("http://localhost:8000/mcp") as client:
    # Use the client
    pass

注： HTTP模式（流式HTTP）专为远程访问和web集成而设计。对于Claude Desktop的本地使用，请使用stdio模式（选项A或B）。

重要： HTTP终结点没有身份验证。任何具有端点网络访问权限的人都可以控制您的Proxmox基础架构。始终使用网络隔离、防火墙或反向代理身份验证。

配置

编辑您的 .env 文件：

# REQUIRED: Accept risks (see DISCLAIMER section)
I_ACCEPT_RISKS=true

# Connection details
HOST=192.168.1.100      # Your Proxmox server IP
SSH_USERNAME=root       # SSH username (NOT Proxmox UI username)
SSH_PASSWORD=your_password  # SSH password

或者使用SSH密钥身份验证：

# REQUIRED: Accept risks (see DISCLAIMER section)
I_ACCEPT_RISKS=true

# Connection details
HOST=192.168.1.100
SSH_USERNAME=root
SSH_KEY=/path/to/your/private_key

可选配置：

# Maximum character limit for command output (default: 25000)
# Increase for larger outputs, decrease to save tokens
CHARACTER_LIMIT=25000

# Enable host command execution (DISABLED by default for security)
# See "Host Command Execution" section for details
ENABLE_HOST_EXEC=false

添加到克劳德桌面

打开克劳德桌面配置：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- 视窗: %APPDATA%\Claude\claude_desktop_config.json
添加此配置（调整安装路径）：

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": ["run", "/full/path/to/proxmox_mcp.py"],
      "env": {
        "I_ACCEPT_RISKS": "true",
        "HOST": "192.168.1.100",
        "SSH_USERNAME": "root",
        "SSH_PASSWORD": "your_password"
      }
    }
  }
}

重要： 您必须设置 "I_ACCEPT_RISKS": "true" 阅读免责声明部分后。

或者如果不使用 uv:

{
  "mcpServers": {
    "proxmox": {
      "command": "python",
      "args": ["/full/path/to/proxmox_mcp.py"],
      "env": {
        "I_ACCEPT_RISKS": "true",
        "HOST": "192.168.1.100",
        "SSH_USERNAME": "root",
        "SSH_PASSWORD": "your_password"
      }
    }
  }
}

重新启动克劳德桌面
通过问克劳德来测试：
```
List my Proxmox containers
```

用法示例

配置后，您可以使用自然语言来管理容器：

基本命令

Show me all my containers

Check the status of container 100

Start container 101

Stop container 102

系统管理

Check disk space and memory usage on container 100

Show me the last 50 lines of syslog on container 101

List all running processes on container 102

软件管理

Update package lists on container 100

Install nginx on container 101

Check if nginx is running on container 102

文件操作

Show me the contents of /etc/nginx/nginx.conf on container 100

List files in /var/www on container 101

Check the size of /var/log directory on container 102

运作原理

You → Claude Desktop → MCP Server → SSH → Proxmox Host → pct exec → Container

你问克劳德一个关于你的集装箱的问题
Claude调用适当的MCP工具
MCP服务器通过SSH连接到Proxmox
用途 pct exec 在容器内运行命令的命令
将结果返回给Claude
克劳德用自然语言向您展示结果

可用工具

服务器提供了Claude可以使用的10个工具：

容器工具

proxmox-container_exec_命令 -在容器中执行任何bash命令
proxmox_list_容器 -列出所有容器及其状态
proxmox_container_status -检查容器是否正在运行或停止
proxmox_start_container -启动已停止的容器
proxmox_stop_container -停止正在运行的容器

文件传输工具

proxmox_download_file_from_container -将文件从容器下载到本地计算机
proxmox_upload_file_to_container -将文件从本地计算机上载到容器
proxmox_download_file_from_host -从Proxmox主机下载文件(⚠️ 需要ENABLE_HOST_EXEC）
proxmox_upload_file_to_host -将文件上传到Proxmox主机(⚠️ 需要ENABLE_HOST_EXEC）

主机工具

proxmox_hostexec_命令 -直接在Proxmox主机上执行命令(⚠️ 默认情况下禁用）

Claude将根据您的问题自动选择使用哪个工具。

文件传输操作

MCP服务器支持在本地计算机和Proxmox容器或主机系统之间传输文件。

运作原理

容器文件传输：

Local Machine ←→ SFTP ←→ Proxmox Host ←→ pct pull/push ←→ Container

主机文件传输：

Local Machine ←→ SFTP ←→ Proxmox Host

配置

添加到您的 .env 文件（可选）：

# Maximum file size in bytes (default: 10MB)
MAX_FILE_SIZE=10485760  # 10 MB

容器文件操作

从容器下载：

Download /etc/nginx/nginx.conf from container 100 to ./nginx.conf

上传到容器：

Upload ./config.yaml to container 101 at /etc/app/config.yaml with permissions 644

克劳德将自动：

根据MAX_file_SIZE限制检查文件大小
防止覆盖文件（除非指定overwrite:true）
在Proxmox主机上使用临时暂存
自动清理临时文件
设置适当的文件权限

主机文件操作

⚠️ 需要 ENABLE_HOST_EXEC=true -请参阅主机命令执行部分。

从主机下载：

Download /etc/pve/storage.cfg from the Proxmox host to ./storage.cfg

上传到主机：

Upload ./backup.sh to Proxmox host at /root/backup.sh with permissions 755

文件传输示例

下载配置文件：

Download nginx configuration from container 100
Get the application log from container 101 at /var/log/app.log
Backup /etc/hosts file from container 102

上传配置文件：

Upload my local nginx.conf to container 100 at /etc/nginx/nginx.conf
Deploy script.sh to container 101 at /root/script.sh with executable permissions

备份和还原：

Download database backup from container 100 at /backups/db.sql
Upload the restored database to container 100 at /tmp/restore.sql

文件大小限制

默认最大文件大小为 10 MB 为了防止：

记忆力衰竭
过度使用代币
传输时间长

要调整限制：

# In your .env file
MAX_FILE_SIZE=52428800  # 50 MB

安全注意事项

文件传输包括以下安全功能：

✅ 路径验证 -防止目录遍历攻击（否 .. 允许） ✅ 大小限制 -强制执行MAX_FILE_SIZE以防止资源耗尽 ✅ 覆盖保护 -除非明确允许，否则不会覆盖现有文件 ✅ 权限控制 -设置上传时的特定文件权限 ✅ 临时文件清理 -即使出现错误，也会自动删除临时文件 ✅ 主机访问控制 -主机文件操作需要ENABLE_Host_EXEC标志

⚠️ 重要提示：

文件通过Proxmox主机传输（需要临时空间）
容器必须正在运行才能进行容器文件操作
上传到主机需要ENABLE_host_EXEC=true
在确认操作之前，始终检查文件路径

文件传输故障排除

错误：“文件太大”

解决方案：在.env文件中增加MAX_FILE_SIZE

错误：“本地文件已存在”

解决方案：删除本地文件或设置overwrite=true

错误：“权限被拒绝”

解决方案：检查SSH用户是否有权访问文件路径

错误：“容器未运行”

解决方案：首先使用以下命令启动容器 proxmox_start_container

错误：“主机文件操作已禁用”

解决方案：设置ENABLE_HOST_EXEC=true以启用主机文件传输

主机命令执行

⚠️ 什么是Host Exec？

主机执行器 允许您直接在Proxmox主机上运行命令，而不是在容器内运行。这使您可以完全访问：

全系统操作（群集状态、存储管理）
创建/管理容器和虚拟机
主机系统资源和诊断
Proxmox特定命令（pct、qm、pvecm等）

🔐 安全警告

这个功能非常强大，而且有潜在的危险！

特性	容器执行	主机执行
范围	单个集装箱	整个基础设施
隔离	受容器保护	无-完全系统访问
影响	一项服务	所有容器/VM
风险等级	中等	🔴 非常高
可能会损坏Proxmox	没有	是
默认状态	已启用	禁用

🚀 如何启用

主机执行器是 默认情况下禁用 为了安全。要启用：

选项1：通过.env文件

# Add to your .env file
ENABLE_HOST_EXEC=true

选项2：通过Claude桌面配置

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": ["run", "/path/to/proxmox_mcp.py"],
      "env": {
        "I_ACCEPT_RISKS": "true",
        "HOST": "192.168.1.100",
        "SSH_USERNAME": "root",
        "SSH_PASSWORD": "your_password",
        "ENABLE_HOST_EXEC": "true"
      }
    }
  }
}

启用后，重新启动Claude Desktop。

📊 何时使用主机与容器执行器

使用Host Exec(proxmox_host_exec_command)用于：

✅ 列出所有容器/VM： pct list, qm list
✅ 正在检查群集状态： pvecm status
✅ 主机资源： df -h, free -h （主机级别）
✅ 存储管理： pvesm status, zpool status, zfs list
✅ 创建容器/VM： pct create, qm create
✅ Proxmox服务： systemctl status pveproxy
✅ 主机上的网络诊断

使用容器执行器(proxmox_container_exec_command)用于：

✅ 在特定容器内运行命令
✅ 在容器中安装软件
✅ 检查容器内的日志
✅ 管理容器内的服务
✅ 容器内的文件操作

🎯 指挥安全级别

✅ SAFE（只读命令）

这些命令只读取信息，不会损害您的系统：

# List containers and VMs
pct list
qm list

# Check cluster status
pvecm status

# Host resources
df -h
free -h
uptime
who

# Storage information
pvesm status
zpool status
zfs list

# Network info
ip addr
ip route

⚠️ 中等风险

这些命令可以进行更改，但通常是安全的：

# Container lifecycle
pct create <vmid> <template> ...
pct start <vmid>
pct stop <vmid>
qm start <vmid>
qm stop <vmid>

# Service management
systemctl restart pveproxy
systemctl status pvedaemon

# Package management
apt update

🔴 高风险

这些命令可能会导致服务中断：

# Destructive operations
pct destroy <vmid>
qm destroy <vmid>

# System changes
apt upgrade -y
apt dist-upgrade

# Service stops
systemctl stop pveproxy

# System control
shutdown -h now
reboot

⛔ 危险-避免

这些命令可能会破坏您的整个系统：

# File deletion
rm -rf /
rm -rf /var
rm -rf /etc

# Disk operations
dd if=/dev/zero of=/dev/sda
mkfs.ext4 /dev/sda1

# Device operations
Commands affecting /dev/*

💡 用法示例

启用host exec后，您可以询问Claude：

系统状态：

Show me all containers and VMs on my Proxmox host
Check my cluster status
What's the disk usage on the Proxmox host?

存储管理：

Show me my ZFS pool status
List all storage on Proxmox
Check the health of my storage

集装箱管理：

Create a new Ubuntu container with ID 200
List all stopped containers
Show me system resource usage on the host

诊断：

Check if Proxmox services are running
Show me network interfaces on the host
What's the uptime of my Proxmox server?

🛡️ 最佳实践

从只读命令开始 -适应 pct list, df -h等等
仅在需要时启用 -保持 ENABLE_HOST_EXEC=false 不主动使用主机命令时
执行前审查 -始终回顾克劳德即将进行的操作，尤其是破坏性操作
尽可能使用容器exec -如果您的任务可以在容器内完成，请改用container-exec
先备份 -在进行重大更改之前，请确保您有备份
在开发环境中测试 -在生产之前在测试环境中尝试命令
监控日志 -运行主机命令时注意系统日志
理解命令 -如果克劳德提出了一个你不理解的命令，请先要求解释

🚨 紧急恢复

如果意外运行了危险的命令：

立即停止 -如果命令仍在运行，您可以通过SSH停止它
检查损坏情况 -快跑 df -h, systemctl status, pct list 评估
从备份中恢复 -如果需要，使用Proxmox备份工具进行还原
寻求帮助 -Proxmox论坛和社区可以帮助恢复

❓ 故障排除

错误：“出于安全考虑，主机命令执行已禁用”

解决方案：通过设置启用主机exec ENABLE_HOST_EXEC=true 在您的配置中。

错误：“权限被拒绝”

解决方案：确保您的SSH用户拥有必要的权限（root通常拥有所有权限）。

命令挂起/耗时太长

解决方案：增加请求中的超时参数，或检查主机是否响应。

安全

⚠️ 关键：请阅读免责声明第一节！

⚠️ 重要安全注意事项：

此服务器具有 完全shell访问 到您的容器，并可能到您的Proxmox主机
命令以SSH用户（通常是root）身份执行 完全权限
人工智能系统将可以直接访问您的基础设施上执行命令
你有责任 用于在执行命令之前对其进行检查
开发商不承担任何责任 任何损坏或数据丢失
尽可能使用SSH密钥而不是密码
保持你的 .env 文件安全（它在 .gitignore)
仅允许来自受信任网络的SSH访问
定期审查日志以监控活动
始终有备份 在生产中使用此工具之前

内置安全功能：

✅ 所有参数的输入验证
✅ 命令超时限制（最多300秒）
✅ 代码中未存储凭据
✅ 基于环境的配置
✅ SSH连接生命周期管理

故障排除

无法连接到Proxmox

错误： Failed to connect to Proxmox host

解决：

验证 HOST 是正确的
检查SSH端口（默认为22）
手动测试SSH： ssh root@your-proxmox-host
检查防火墙规则

未找到容器

错误： Container {vmid} not found

解决：

让克劳德先列出所有容器
验证容器ID是否正确
检查Proxmox web UI中是否存在容器

权限不足

错误： Permission denied

解决：

验证SSH凭据是否正确
确保用户有运行权限 pct 命令
Root用户通常具有所有必需的权限

命令超时

错误： Command execution timeout

解决：

一些命令需要更长的时间（例如。， apt upgrade)
您可以在请求中增加超时时间
检查容器是否响应

为什么选择SSH而不是Proxmox API？

在研究了Proxmox API之后，我们发现：

❌ Proxmox API有非支持在容器中直接执行命令
❌ 这 /nodes/{node}/execute 端点用于API调用，而不是shell命令
✅ pct exec 通过SSH 官方推荐的方法
✅ 适用于现有的Proxmox设置，无需额外配置
✅ 提供对容器的完全bash访问

技术细节

语言： Python 3.10+
框架： FastMCP（模型上下文协议）
SSH库： 参数
验证： Pydantic v2
格式： PEP 723（内联依赖）

项目结构

proxmox-mcp-server/
├── proxmox_mcp.py                      # Main MCP server (PEP 723)
├── .env.example                        # Configuration template
├── stack.env                           # Stack/Portainer environment template
├── claude_desktop_config.example.json  # Claude Desktop config example
├── Dockerfile                          # Docker image definition
├── docker-compose.yml                  # Docker Compose configuration
├── .dockerignore                       # Docker build exclusions
└── README.md                           # This file

贡献

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

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

问题： GitHub问题
讨论： GitHub讨论

致谢

建于 FastMCP
跟随模型上下文协议规格
用途参数用于SSH连接

使用说明

Proxmox MCP服务器

⚠️ 免责声明/罚款

✅ 强制风险接受

这是什么？

特性

快速开始

先决条件

安装

Docker部署详细信息

配置

添加到克劳德桌面

用法示例

基本命令

系统管理

软件管理

文件操作

运作原理

可用工具

容器工具

文件传输工具

主机工具

文件传输操作

运作原理

配置

容器文件操作

主机文件操作

文件传输示例

文件大小限制

安全注意事项

文件传输故障排除

主机命令执行

⚠️ 什么是Host Exec？

🔐 安全警告

🚀 如何启用

📊 何时使用主机与容器执行器

🎯 指挥安全级别

💡 用法示例

🛡️ 最佳实践

🚨 紧急恢复

❓ 故障排除

安全

故障排除

无法连接到Proxmox

未找到容器

权限不足

命令超时

为什么选择SSH而不是Proxmox API？

技术细节

项目结构

贡献

许可证

支持

致谢

相关项目

相关 MCP

Flomo笔记服务

3D资产生成服务

文档搜索服务

Microsoft 365命令行管理服务器

AI文本人性化服务

APISIX MCP服务器