VMware_MCP_SERVER

Комплексный Model Context Protocol (MCP) сервер для управления VMware vSphere, предоставляющий AI-агентам полный доступ к операциям виртуальной инфраструктуры через безопасное Docker-окружение. 55+ инструментов в 12 категориях, включая полный набор read-only vSAN мониторинга (10 инструментов) и получение guest IP через pyVmomi (2 инструмента).

Основные улучшения

• ✅ Исправлены критические баги (requirements, REST endpoints, SSL)
• ✨ Добавлены инструменты для real-time метрик через pyVmomi PerformanceManager
• ✨ Добавлен полный набор vSAN read-only мониторинга (10 инструментов, Phase 0-5)
• ✨ Добавлены guest IP tools (get_vm_ip, list_vm_ips) — REST API vCenter не отдаёт guest IP, реализация через pyVmomi vm.guest (Phase 6)
• 🔒 CA-aware SSL для безопасных production-соединений
• 📚 Расширенная документация на русском языке
• 🎯 SKILL.md / EXAMPLE_SKILL.md — готовые к использованию гайды для AI-агентов

---

Возможности

Управление виртуальными машинами

• Список ВМ — получение всех виртуальных машин с состояниями питания
• Детали ВМ — подробная информация о конкретных ВМ
• Операции питания — запуск, остановка, перезагрузка ВМ
• Мониторинг ресурсов — использование CPU, RAM и сети
• Информация о хранилище — использование дисков и датасторов
• Guest IP — get_vm_ip (детально по одной ВМ) и list_vm_ips (сводка по всем ВМ) через pyVmomi vm.guest

Продвинутые операции

• Управление snapshot'ами — создание, список и удаление снимков ВМ
• Управление template'ами — список и управление шаблонами ВМ
• Массовые операции — операции питания над множеством ВМ
• Модификация ресурсов — изменение выделения CPU и памяти
• Управление сетью — port groups и конфигурация сети

Мониторинг и отчётность

• Мониторинг производительности — real-time использование ресурсов через pyVmomi PerformanceManager
• Логирование событий — события ВМ и системные логи
• Управление алармами — активные алармы и оповещения
• Комплексные отчёты — аналитика по всему окружению
• Использование ресурсов — метрики CPU, памяти, диска и сети

Функции безопасности

• Система подтверждения — все деструктивные операции требуют явного подтверждения
• Обработка ошибок — понятные сообщения об ошибках и troubleshooting
• Безопасная аутентификация — управление credentials через переменные окружения с CA-aware SSL
• Audit trail — прозрачное логирование всех операций

---

Новые инструменты

✨ Real-time метрики через pyVmomi

get_vm_metrics

Получение детальных метрик производительности виртуальной машины:

• CPU: usage/ready
• Memory: active/consumed
• Disk: read/write/latency
• Network: received/transmitted

Важно: Для guest-level метрик требуется VMware Tools. Выключенные ВМ не возвращают realtime данные.

get_host_metrics

Получение детальных метрик производительности ESXi хоста:

• Те же метрики, что для ВМ
• Детализация по ядрам CPU
• Агрегированная статистика

🔧 Исправленные инструменты

• get_alarms — теперь работает через pyVmomi AlarmManager (был 404)
• get_vm_events — теперь работает через pyVmomi EventManager (был 404)
• get_host_details — исправлен workaround для vCenter 8.0.3+

🛰️ vSAN monitoring (10 read-only инструментов, Phase 0-4)

Все инструменты vSAN — строго read-only (Tier 1). Деструктивные vSAN-операции (add/remove/claim disk, evacuate, witness add/remove) НЕ реализованы и не входят в scope. Бэкенд: pyVmomi SOAP на /vsanHealth endpoint (vim.version.version11); исключение — get_vsan_storage_policies через REST.

• list_vsan_clusters — все vSAN-enabled кластеры с числом хостов, MoRef, vSAN UUID
• get_vsan_cluster_health — overall 🟢/🟡/🔴 + per-host через VsanVcClusterHealthSystem
• get_vsan_capacity_info — total/free/used TB через VsanSpaceReportSystem
• get_vsan_disk_groups — cache SSD + capacity tier per host через QueryDiskMappings (per-host итерация обязательна)
• get_vsan_performance_metrics — IOPS, throughput, latency, congestion для кластера через VsanPerformanceManager
• get_vsan_health_checks — overall + 9 health-групп + per-host node state (master/backup/agent)
• get_vsan_objects — все vSAN объекты с разбивкой по типам (vdisk/namespace/vmswap/...) и SPBM-профилям
• get_vsan_storage_policies — все SPBM-политики vCenter (REST), фильтр по vSAN-related
• get_vsan_capabilities — 122+ фичи vCenter с иконками по категориям
• get_vsan_witness_info — witness host(s) для stretched кластеров; graceful "not stretched" для обычных

Известные ограничения (vCenter 8.0.3):

• vSAN-specific REST endpoints (vcenter/vsan/*) → 404 (не существуют), используется pyVmomi
• SPBM detail endpoints (/pbm/profile, /vcenter/storage/policies/{id}) → 404, политики показывают только name/id/description
• Compliance endpoints (/vcenter/storage/policies/compliance*) → 404 (доступны с 8.0 U3+)
• Witness IP/connectivity недоступны через API (только через vSphere Client UI)
• Idle vSAN кластеры возвращают пустые perf-samples — это валидный production-state, не ошибка

🌐 Guest IP retrieval (Phase 6)

REST API vCenter не отдаёт guest IP в принципе — он живёт только в vim.vm.GuestInfo, доступном через pyVmomi SOAP. Реализовано 2 read-only инструмента (Tier 1):

• get_vm_ip(vm_name, hostname=None) — детальный guest IP одной ВМ через pyVmomi vm.guest: primary IP + guest hostname + VMware Tools version + per-NIC (network, MAC, connected, IPv4/IPv6 + prefixLength). Graceful fallback если ВМ не найдена / не powered on / Tools не запущены.
• list_vm_ips(hostname=None) — одноразовая сводка через один PropertyCollector-запрос: имя + power state + guest IP для каждой powered-on ВМ с работающим Tools (templates пропускаются). Удобно для network inventory и "find VM by IP".

Требования: ВМ должна быть powered on и VMware Tools должна быть запущена (данные живут в vm.guest, без Tools = нет guest info). Live-протестировано на cluster12: FF-UPTIME-3 → 10.20.34.159.

Подробности в SKILL.md → секция "Virtual Machines — listing & details".

⚠️ Интерпретация метрик памяти

При работе с get_vm_metrics:

• mem.active — реально используемая память процессами гостевой ОС (ключевая метрика!)
• mem.consumed — зарезервировано ESXi гипервизором (включает overhead, кэши, balloon driver)
• Не путайте: consumed ≠ используется гостем. Если active = 53 MB при consumed = 4 GB, то гость использует только 53 MB.

---

Установка

Требования

• Docker и Docker Compose
• VMware vCenter Server 8.0+ с доступом к REST API
• Действительные credentials vCenter

Быстрый старт

1. Клонируйте репозиторий

git clone https://github.com/yourusername/VMW-vsphere-mcp-server.git
cd VMW-vsphere-mcp-server

2. Настройте окружение

cp env.example .env
# Отредактируйте .env своими credentials vCenter

3. Разверните через Docker

docker compose up -d

---

Конфигурация

Переменные окружения

Создайте .env файл со следующими переменными:

# Подключение к vCenter
VCENTER_HOST=vcenter.example.com
VCENTER_USER=username@vsphere.local
VCENTER_PASSWORD=your_password_here
INSECURE=False

# Опционально: CA сертификат для проверки SSL
REQUESTS_CA_BUNDLE=/path/to/ca-bundle.crt
# или
VCENTER_CA_BUNDLE=/path/to/vcenter-ca.crt

# Конфигурация сервера
SERVER_HOST=0.0.0.0
SERVER_PORT=8000

Интеграция с MCP клиентом

Пример конфигурации для MCP клиентов:

{
  "mcpServers": {
    "vsphere-mcp-server": {
      "name": "vSphere MCP Server",
      "type": "streamable",
      "url": "http://vsphere-mcp-server:8000/mcp",
      "auth_token": null,
      "enabled": true
    }
  }
}

---

Использование SKILL.md

В репозитории включён файл SKILL.md — комплексный гайд для использования всех 55+ инструментов MCP с AI-агентами.

Что включено в SKILL.md

• Полный список инструментов — все 55+ инструментов по 12 категориям (включая vSAN monitoring + guest IP)
• Паттерны использования — правильные способы вызова инструментов
• Примеры команд — ready-to-use примеры для типичных задач
• Система безопасности — какие операции требуют подтверждения
• Интерпретация метрик — как правильно читать performance данные
• Workflows — end-to-end сценарии (клонирование ВМ, snapshot'ы, мониторинг, vSAN audit)

Использование с AI-агентами

SKILL.md специально отформатирован для загрузки в контекст AI-агентов:

# Пример: загрузка скилла в Claude Code
# Скилл автоматически доступен через skills директорию

AI-агент с загруженным SKILL.md:

• ✅ Знает все доступные инструменты
• ✅ Понимает правильные паттерны вызова
• ✅ Может выполнять комплексные workflows
• ✅ Соблюдает safety guardrails (подтверждения для деструктивных операций)

---

Доступные инструменты

Полный список см. в SKILL.md. Основные категории:

Управление ВМ

• list_vms, get_vm_details, get_vm_metrics
• power_on_vm, power_off_vm, restart_vm
• clone_vm, delete_vm, modify_vm_resources

Управление инфраструктурой

• list_hosts, get_host_details, get_host_metrics
• list_datastores, list_networks, list_datacenters

Мониторинг и производительность

• get_vm_performance_info, get_host_performance_info
• get_vm_disk_usage, get_datastore_usage
• get_vms_with_high_resource_usage

Управление snapshot'ами

• list_vm_snapshots, create_vm_snapshot, delete_vm_snapshot

Продвинутый мониторинг

• get_vm_events, get_alarms, get_port_groups

Отчётность и аналитика

• generate_vm_report, get_resource_utilization_summary

🛰️ vSAN monitoring (read-only)

• list_vsan_clusters — список vSAN-кластеров
• get_vsan_cluster_health, get_vsan_capacity_info, get_vsan_disk_groups
• get_vsan_performance_metrics, get_vsan_health_checks
• get_vsan_objects, get_vsan_storage_policies, get_vsan_capabilities
• get_vsan_witness_info — для stretched кластеров

⚠️ Деструктивные операции требуют явного подтверждения через confirm=True ⚠️ Все vSAN-инструменты — read-only (Tier 1), деструктивные vSAN-операции не реализованы

---

Технические детали

Зависимости

• Python: 3.12+
• pyvmomi: 9.1.0.0 (VMware vSphere Python SDK)
• mcp: 1.14.1 (Model Context Protocol)
• requests: 2.32.5
• FastMCP для реализации MCP сервера

Протестировано на

• vCenter Server 8.0.3 (builds 24022515, 24322831)
• ESXi 8.0.x хосты
• Python 3.12

Архитектура

• REST API (vsphere_client.py) — для inventory и mutating операций
• SOAP/pyVmomi (pyvmomi_client.py) — для алармов, событий, метрик, vSAN (/vsanHealth endpoint), guest IP (vm.guest) и продвинутых операций
• FastMCP (server.py) — реализация MCP протокола с 55+ инструментами (12 категорий)

---

Примеры использования

Базовые операции с ВМ

# Список всех ВМ
"Покажи все виртуальные машины"

# Детали ВМ и метрики
"Получи детали для ВМ WebServer01"
"Покажи использование CPU и памяти для ВМ WebServer01"

# Операции питания
"Включи ВМ DatabaseServer"
"Перезагрузи ВМ: WebServer01, WebServer02"

🌐 Guest IP (поиск ВМ по IP / inventory)

# Получить IP одной ВМ (детально: hostname, Tools version, per-NIC)
"Какой IP у ВМ FF-UPTIME-3?"
"Покажи детальный guest IP для WebServer01"

# Сводка IP по всем ВМ
"Покажи IP всех ВМ"
"Найди ВМ с IP 10.20.34.159"

Мониторинг производительности

# Real-time метрики
"Получи метрики производительности для ВМ WebServer01"
"Покажи метрики хоста host-21"

# Агрегированные метрики
"Покажи использование CPU и памяти для всех ВМ"
"Какие ВМ имеют высокое использование ресурсов?"

# Мониторинг хранилища
"Покажи использование датасторов"
"Какие ВМ имеют использование диска более 90%?"

Мониторинг и отчётность

# События и алармы
"Покажи последние события для ВМ DatabaseServer"
"Получи активные алармы в окружении"
"Покажи алармы только для виртуальных машин"

# Комплексные отчёты
"Сгенерируй полный отчёт по vSphere окружению"
"Покажи сводку использования ресурсов"

🛰️ vSAN мониторинг (read-only)

# Inventory vSAN кластеров
"Покажи все vSAN кластеры"
"Какие vSAN кластеры в окружении?"

# Health и capacity
"Получи общий статус здоровья vSAN кластера New Cluster 122"
"Сколько свободного места в vSAN кластере New Cluster 122?"

# Производительность и объекты
"Покажи disk groups для vSAN кластера New Cluster 122"
"Сколько vSAN объектов в кластере New Cluster 122?"
"Покажи vSAN-related storage policies"

# Stretched cluster / witness
"Есть ли witness host для vSAN кластера New Cluster 122?"

---

Функции безопасности

Система подтверждения

Все деструктивные операции требуют явного подтверждения:

# Первый вызов - показывает предупреждение
delete_vm(vm_id="TestServer", confirm=False)
# Возвращает: ⚠️ ДЕСТРУКТИВНАЯ ОПЕРАЦИЯ: Удаление ВМ TestServer...

# Второй вызов - выполняет операцию
delete_vm(vm_id="TestServer", confirm=True)
# Возвращает: ⚠️ ВМ TestServer успешно удалена

Аутентификация через переменные окружения

• Credentials хранятся в переменных окружения
• Нет захардкоженных паролей
• Безопасный Docker deployment
• Поддержка SSL/TLS с проверкой CA сертификата

---

Контрибьютор

• DanilenkA — автор всех улучшений и исправлений

---

Лицензия

Apache 2.0 License

---

Поддержка

По вопросам и проблемам открывайте issue в репозитории.