# vcenter-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/vcenter-mcp?cacheSeconds=300)](https://pypi.org/project/vcenter-mcp/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)

Ask GitHub Copilot questions about your Broadcom VCF and VMware vCenter environment in plain English — clusters, datacenters, datastores, folders, hosts, networks, resource pools, VMs, guest details, appliance version and time, and more — directly from VS Code.

Supports **Broadcom VCF vCenter Server Appliance** and **VMware vCenter Server Appliance** — with per-vCenter credentials stored securely in your OS keyring (Windows Credential Manager / macOS Keychain / Linux Secret Service).

## Requirements

- [Python 3.10+](https://www.python.org/downloads/)
- [VS Code](https://code.visualstudio.com/)
- GitHub Copilot + Copilot Chat extensions

## Quick start

```bash
# 1. Install
pip install vcenter-mcp

# 2. Create a folder for your inventory, navigate to it, and run the wizard
mkdir my-vcenter && cd my-vcenter
vcenter-mcp configure
```

The wizard will:
- Verify Python 3.10+ is active
- Install / update all dependencies
- Register your vCenter Server Appliance instance(s) in `inventory.yaml`
- Store credentials **securely in the OS keyring** — no plain-text passwords anywhere
- Write `.vscode/mcp.json` pointing VS Code at the server (no credentials in this file)

```bash
# 3. Open the folder in VS Code
code .
```

In VS Code, open Copilot Chat, switch to **Agent mode**, and start asking questions.

> **Already set up?** Re-run `vcenter-mcp configure` at any time to add new vCenter instances and to update credentials.

## Configuration

### Credential storage

Credentials are stored in the OS keyring under the service name `vcenter-mcp`. Key format:

| Entity | Keyring key examples |
|---|---|
| vCenter (default) | `vcenter.default.username`, `vcenter.default.password` |
| vCenter (override) | `vcenter.VCENTER-NAME.username`, `vcenter.VCENTER-NAME.password` |

Lookup falls back from named entry → `vcenter.default.*` → environment variables (`VCENTER_USERNAME` etc.) for compatibility and automation.

### vCenter inventory — `inventory.yaml`

Register your instances here. Edit directly or re-run `vcenter-mcp configure`.

```yaml
vcenters:
  - name: PROD-VCENTER-1
    fqdn: vcsa01.example.local
    ip_address: 192.168.1.10
    verify_ssl: false

  - name: PROD-VCENTER-2
    fqdn: vcsa02.example.local
    ip_address: 192.168.1.11
    verify_ssl: true
```

- `name` — label used in prompts and tool parameters (`vcenter_name`)
- `fqdn` or `ip_address` — at least one is required; if both are provided, `fqdn` is preferred
- Single entry → selected automatically; multiple entries → specify the name in your prompt

### VS Code — `.vscode/mcp.json`

Generated by `vcenter-mcp configure`. Contains no credentials:

```json
{
  "servers": {
    "vcenter-mcp": {
      "type": "stdio",
      "command": "vcenter-mcp",
      "env": {
        "VCENTER_MCP_INVENTORY": "${workspaceFolder}/inventory.yaml"
      }
    }
  }
}
```

## Usage

Switch Copilot Chat to **Agent mode** and ask in plain English:

```
List all VMs and their power state
Show me all clusters and datacenters
Which hosts are in the cluster and what version are they running?
List all datastores and their free capacity
Show me the networks in vCenter
Get guest identity details for VM <vm-id>
Show me the appliance version and time
```

Target a specific vCenter by name:

```
List all VMs from PROD-VCENTER-1
Show appliance version for PROD-VCENTER-1
List all datastores from PROD-VCENTER-2
```

Copilot calls `list_vcenters` automatically when needed to discover available entries.

## Project structure

```
vcenter-mcp/
├── inventory.yaml              vCenter registry (user-generated)
├── pyproject.toml              Package metadata and dependencies
├── available_tools.md          Full tool reference
├── SECURITY_POSTURE.md         Security posture, cautions, and operational guidance
└── src/
    └── vcenter_mcp/
        ├── __init__.py
        ├── app.py              Shared FastMCP instance ("vcenter-mcp")
        ├── cli.py              Entry point — 'vcenter-mcp' and 'vcenter-mcp configure'
        ├── server.py           Thin wrapper delegating to cli.main()
        ├── credentials.py      OS keyring read/write helpers
        ├── registry.py         Inventory loading, host+credential resolver, JSON helper
        ├── client.py           HTTP client: session auth and policy-validated GET requests
        ├── security.py         Central security policy, limits, and startup config validation
        ├── vsphere_ws.py       vSphere Web Services helpers for ESXi host detail
        └── tools/
            ├── inventory.py            list_vcenters, get_vcenter_inventory
            ├── vcenter_inventory.py    list_clusters, get_cluster,
            │                           get_cluster_resource_utilization_ws,
            │                           get_cluster_cpu_memory_utilization_period_ws,
            │                           get_cluster_cpu_memory_daily_rollup_ws,
            │                           get_cluster_cpu_memory_utilization_window_ws,
            │                           list_datacenters, get_datacenter,
            │                           list_datastores, get_datastore,
            │                           list_folders,
            │                           list_hosts, get_host,
            │                           list_networks,
            │                           list_resource_pools, get_resource_pool,
            │                           list_vms, get_vm
            ├── vm_details.py           get_vm_guest_identity, list_vm_guest_local_filesystems,
            │                           list_vm_guest_network_interfaces, get_vm_hardware,
            │                           get_vm_boot, get_vm_cpu, get_vm_memory,
            │                           list_vm_disks, get_vm_disk,
            │                           list_vm_nics, get_vm_nic
            └── appliance.py            get_appliance_version, get_appliance_time
```

See [available_tools.md](https://github.com/veg-salad/vcenter_mcp/blob/main/available_tools.md) for the full tool reference including parameters, return values, and source modules.

## Notes

- All tools are **read-only** — no changes are made to your vCenter environment
- Uses the vCenter REST API at `/api/*` over HTTPS, typically port 443
- Uses the vSphere Web Services API through vCenter for `list_hosts` and `get_host`, because REST host detail coverage is not available in vCenter API surface
- Cluster window utilization tool behavior: supports `1-30` day windows and hour inputs only when they are multiples of 24 (for example `24 hours`, `168 hours`)
- Historical utilization output depends on PerformanceManager retention in your vCenter; requested windows may return fewer samples if older data is not retained
- Authentication uses `POST /api/session` and reuses the session token for tool calls
- If multiple vCenters are configured, specify `vcenter_name` to target the correct instance
- Transport is **stdio** — the server runs locally and is managed by VS Code

## Security

See [SECURITY_POSTURE.md](https://github.com/veg-salad/vcenter_mcp/blob/main/SECURITY_POSTURE.md) for current security controls, hardening behavior, and operational cautions.

## Disclaimer

This is an independent, community-built project and is **not an official Broadcom or VMware product**. It is not affiliated with, endorsed by, or supported by Broadcom Inc. or VMware by Broadcom in any way. VMware, vSphere, vCenter, and VCF are trademarks of their respective owners.