vSphere MCP Pro
适用于VMware vCenter 8.0+的安全、功能丰富的模型上下文协议(MCP)服务器。
通过MCP工具公开受控的vCenter操作,包括VM生命周期管理、快照操作、数据存储/主机发现等,以及审计日志、RBAC授权、会话池和速率限制。
目录
- 概述
- 主要特点
- 建筑
- 目录结构
- 安装
- 配置
- 运行服务器
- 可用工具/API
- 错误处理
- 审计日志
- 速率限制
- 安全模型
- 发展
- Docker使用
- 故障排除
- 更新日志
- 许可证
概述
vsphere-mcp-pro 是专为VMware vCenter 8.0+环境设计的MCP服务器。
它提供:
- 安全、结构化地访问vCenter操作
- 通过角色进行严格授权→ 允许的工具
- 快照+虚拟机生命周期操作
- 安全多租户使用的审计和速率限制
- 对两者的支持
/api(首选)和/restvCenter端点 - 可选主机允许列表,以防止意外的跨集群操作
- 连接池可防止vCenter会话耗尽
服务器运行时使用 FastMCP 并自动将每个工具操作包装为:
- 基于令牌的RBAC(
Authorizer) - 令牌桶速率限制
- JSONL审计日志记录
- 破坏性操作的确认要求
- 使用详细的vCenter错误上下文进行正确的错误处理
主要特点
✔ 设计安全
- 默认情况下启用SSL验证
- 可选CA捆绑包支持
- 允许的主机实施可防止未经授权的vCenter目标
✔ 强授权模型
- 代币→ 角色映射
- Role → 允许的工具映射
- 除非明确禁用,否则强制执行
- 破坏性操作需要
confirm=True
✔ 操作稳健
- vCenter API调用的自动重试逻辑(
Retry + HTTPAdapter) - 401会话自动续订
- 具有自动清理功能的连接池
- 关机时正确注销会话
- 用于审计和可观察性的广泛日志记录
- 具有vCenter错误上下文的丰富错误消息
✔ 高性能
- 线程安全vCenter会话池(每台主机一个会话)
- 消除了每次请求的身份验证开销
- MCP服务器内置
uvicorn
建筑
关键模块:
-
server.py
构建MCP服务器,注册所有工具,注入授权、速率限制、会话池和审计包装器。 -
vsphere_client.py
处理VMware vCenter的重试、身份验证、会话池和REST/API模式切换。包括: -
VsphereClient-威胁安全的vCenter REST API客户端 VsphereClientPool-具有自动清理功能的连接池-
VsphereApiError-API错误的丰富异常类 -
authz.py
实施: -
代币→ 角色解析
- Role → 刀具浇口
-
令牌桶速率限制
-
audit.py
为每个操作写入JSON行日志。 -
config.py
将环境变量加载到类型化AppConfig使用pydantic.
目录结构```
/
├── vsphere_mcp_pro/ # Python package
│ ├── init.py
│ ├── server.py # MCP server and tool definitions
│ ├── vsphere_client.py # vCenter client, pool, and exceptions
│ ├── authz.py # Authorization and rate limiting
│ ├── audit.py # Audit logging
│ └── config.py # Configuration loading
├── pyproject.toml # Project metadata and dependencies
├── README.md
├── CHANGELOG.md
├── LICENSE
├── env.example # Example environment configuration
└── Dockerfile
______________________________________________________________________
## 安装
### 先决条件
- python **3.10+**
- VMware vCenter **8.0+**
- 有效的API证书
### 从源代码安装```bash
git clone https://github.com/Warezloder/vSphere-MCP-Pro
cd vSphere-MCP-Pro
pip install -e .
配置
配置是由环境驱动的。复制示例文件:```bash
cp env.example .env
### 所需的环境变量
|变量|描述|
| ----------------------- | --------------------------------------------- |
| `VCENTER_HOST` |vCenter主机名/IP|
| `VCENTER_USER` |vCenter用户名|
| `VCENTER_PASSWORD` |vCenter密码|
| `ROLES_TO_TOOLS` |JSON角色映射→ 允许的工具|
| `TOKENS_TO_ROLES` |令牌的JSON映射→ 角色|
| `ALLOWED_VCENTER_HOSTS` |多主机部署的可选分配列表|
### 可选环境变量
|变量|默认值|描述|
| -------------------- | -------------------- | ------------------------------------ |
| `VSPHERE_API_MODE` | `api` |API模式: `api` 或 `rest` |
| `INSECURE` | `false` |禁用SSL验证|
| `VCENTER_CA_BUNDLE` ||自定义CA捆绑包的路径|
| `VCENTER_TIMEOUT_S` | `20` |请求超时(秒)|
| `VCENTER_RETRIES` | `3` |重试次数|
| `VCENTER_BACKOFF` | `0.5` |重试回退系数|
| `SERVER_HOST` | `0.0.0.0` |服务器绑定地址|
| `SERVER_PORT` | `8000` |服务器端口|
| `MCP_PATH` | `/mcp` |MCP端点路径|
| `AUDIT_LOG_PATH` ||审核日志文件(空白=stdout)|
| `AUTH_ENFORCE` | `true` |强制RBAC|
| `RATE_LIMIT` | `true` |启用速率限制|
| `RATE_LIMIT_RPS` | `5` |每秒请求数|
| `RATE_LIMIT_BURST` | `10` |爆裂余量|
### 配置示例```bash
VCENTER_HOST=vcenter.example.com
VCENTER_USER=administrator@vsphere.local
VCENTER_PASSWORD=s3cret
TOKENS_TO_ROLES={"token1": "read", "token2": "ops", "token3": "admin"}
ROLES_TO_TOOLS={"read":["list_vms","get_vm_details"],"ops":["power_on_vm","power_off_vm"],"admin":["delete_vm"]}
运行服务器
本地执行```bash
python -m vsphere_mcp_pro.server
服务器默认值(通过环境变量覆盖):
- 主持人: `0.0.0.0`
- 端口: `8000`
- MCP路径: `/mcp`
______________________________________________________________________
## 可用工具/API
下面是服务器公开的可用MCP工具的分类摘要。
### VM发现
|工具|说明|
| ----------------- | --------------------- |
| `list_vms` |列出所有虚拟机|
| `get_vm_details` |按ID获取VM详细信息|
### 库存发现
|工具|说明|
| -------------------------------- | ------------------------------ |
| `list_hosts` |列出ESXi主机|
| `list_datastores` |列出数据存储|
| `list_networks` |列出网络|
| `list_datacenters` |列出数据中心|
| `get_datastore_usage` |获取数据存储容量/使用情况|
| `get_resource_utilization_summary` |所有资源汇总|
### 动力操作
|工具|说明|
| -------------- | ---------------- |
| `power_on_vm` |打开虚拟机电源|
| `power_off_vm` |关闭虚拟机电源|
| `restart_vm` |重新启动虚拟机|
### 快照操作
|工具|说明|
| -------------------- | ---------------------------------------- |
| `list_vm_snapshots` |列出VM的快照|
| `create_vm_snapshot` |创建快照|
| `delete_vm_snapshot` |删除快照(**需要确认**) |
### 破坏性操作(要求 `confirm=True`)
|工具|说明|
| --------------------- | ---------------------------------- |
| `delete_vm` |永久删除虚拟机|
| `delete_vm_snapshot` |删除快照|
| `modify_vm_resources` |修改CPU/内存(需要关闭电源)|
______________________________________________________________________
## 错误处理
服务器通过提供丰富的错误上下文 `VsphereApiError` 例外情况:```
VsphereApiError: Failed to get VM 'vm-999': HTTP 404 on /api/vcenter/vm/vm-999 [NOT_FOUND]: The VM was not found.
错误响应包括:
- HTTP状态代码
- API路径
- vCenter错误类型(例如。,
NOT_FOUND,ALREADY_EXISTS) - 来自vCenter的人类可读错误消息
例外提供了便利属性:
is_not_found-404或NOT_FOUND错误is_unauthorized-401错误is_forbidden-403错误is_conflict-409错误
审计日志
每个MCP工具调用都记录为JSON行,其中包含:
- 工具名称
- 执行状态(正常/错误)
- 持续时间(ms)
- 山宁泰参数(密码和令牌被屏蔽)
- 错误信息(如有)
- 角色+主机上下文
默认情况下,日志写入stdout,或写入 AUDIT_LOG_PATH 如果已配置。
速率限制
使用令牌桶策略:
- 可配置的
RATE_LIMIT_RPS和RATE_LIMIT_BURST - 每个令牌有单独的桶
- 通过设置禁用
RATE_LIMIT=false
安全模型
| 机制 | 目的 |
|---|---|
| SSL验证 | 防止MITM攻击 |
| 允许的主机列表 | 防止未经授权的目标选择 |
| 角色→ 工具映射 | 强制最小特权原则 |
| 令牌身份验证 | 多租户安全访问 |
| 所需确认 | 防止意外破坏性操作 |
| 速率限制 | 保护vCenter和MCP服务器 |
| 会话池 | 防止vCenter会话耗尽 |
发展
安装dev-deps```bash
pip install -e .[dev]
### 使用自动回放运行```bash
uvicorn vsphere_mcp_pro.server:main --reload
Docker使用
构建```bash
docker build -t vsphere-mcp-pro .
### 跑```bash
docker run \
--rm \
-p 8000:8000 \
--env-file .env \
vsphere-mcp-pro
故障排除
“登录失败:HTTP 401”
- 验证vCenter用户名/密码
- 确保API模式正确(
VSPHERE_API_MODE=api|rest)
“主机名不在允许的集合中”
- 将主机名添加到
ALLOWED_VCENTER_HOSTS
速率限制错误
- 增加
RATE_LIMIT_BURST - 调整每个令牌的使用情况
SSL证书问题
- 集
VCENTER_CA_BUNDLE到您的CA捆绑包路径 - 或禁用SSL验证(不推荐):
INSECURE=true
VsphereApiError异常
- 检查错误消息以了解vCenter特定的详细信息
- 使用
error.is_not_found,error.is_forbidden等,用于程序化处理 - 验证VM/资源ID是否存在
更新日志
看 更改日志.md 查看版本历史和更改。
许可证
该项目根据MIT许可证获得许可。看 许可证 了解详情。
