Vsphere MCP Pro

vSphere MCP Pro

适用于VMware vCenter 8.0+的安全、功能丰富的模型上下文协议（MCP）服务器。

通过MCP工具公开受控的vCenter操作，包括VM生命周期管理、快照操作、数据存储/主机发现等，以及审计日志、RBAC授权、会话池和速率限制。

______________________________________________________________________

目录

• 概述
• 主要特点
• 建筑
• 目录结构
• 安装
• 配置
• 运行服务器
• 可用工具/API
• 错误处理
• 审计日志
• 速率限制
• 安全模型
• 发展
• 故障排除
• 更新日志
• 许可证

______________________________________________________________________

概述

vsphere-mcp-pro 是专为VMware vCenter 8.0+环境设计的MCP服务器。

它提供：

• 安全、结构化地访问vCenter操作
• 通过角色进行严格授权→ 允许的工具
• 快照+虚拟机生命周期操作
• 安全多租户使用的审计和速率限制
• 对两者的支持 /api （首选）和 /rest vCenter端点
• 可选主机允许列表，以防止意外的跨集群操作
• 连接池可防止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证书

从源代码安装

git clone https://github.com/Warezloder/vSphere-MCP-Pro
cd vSphere-MCP-Pro
pip install -e .

______________________________________________________________________

配置

配置是由环境驱动的。复制示例文件：

cp env.example .env

所需的环境变量

可选环境变量

配置示例

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

______________________________________________________________________

运行服务器

本地执行

python -m vsphere_mcp_pro.server

服务器默认值（通过环境变量覆盖）：

• 主持人： 0.0.0.0
• 端口： 8000
• MCP路径： /mcp

______________________________________________________________________

可用工具/API

下面是服务器公开的可用MCP工具的分类摘要。

VM发现

库存发现

动力操作

快照操作

破坏性操作（要求 confirm=True)

______________________________________________________________________

错误处理

服务器通过提供丰富的错误上下文 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

______________________________________________________________________

安全模型

______________________________________________________________________

发展

安装dev-deps

pip install -e .[dev]

使用自动回放运行

uvicorn vsphere_mcp_pro.server:main --reload

______________________________________________________________________

Docker使用

构建

docker build -t vsphere-mcp-pro .

跑

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许可证获得许可。看 许可证 了解详情。