VMware Aria Operations MCP Skill

Note: In VCF 9.0 and later, VMware Aria Operations has been rebranded as VCF Operations. This skill works against both names — the /suite-api/ REST endpoints are unchanged.

Author: Wei Zhou, VMware by Broadcom — wei-wz.zhou@broadcom.com This is a community-driven project by a VMware engineer, not an official VMware product. For official VMware developer tools see developer.broadcom.com.

AI-assisted monitoring and capacity planning for VMware Aria Operations (vRealize Operations) via the Model Context Protocol (MCP).

Python 3.10+ License: MIT

Overview

vmware-aria exposes 44 MCP tools for interacting with Aria Operations through natural language AI agents (Claude Code, Cursor, Goose, etc.):

Category Tools Type
Resources list, get, metrics, health badge, top consumers, metric keys, properties, relationships Read-only (8)
Alerts list, get, investigate (alert→resource), acknowledge, cancel, definitions, notes (list / add), recommendations Read + 3 Write (9)
Alert Definitions symptom definitions, create, enable/disable, delete Read + 3 Write (4)
Capacity overview, remaining, time-remaining, rightsizing Read-only (4)
Reports definitions, generate, list, get, delete Read + 2 Write (5)
Anomaly list anomalies, risk badge Read-only (2)
Health platform health, collector groups, Aria node memory/swap/heap, adapter collection state Read-only (4)
Maintenance start / end resource maintenance, maintenance schedules Read + 2 Write (3)
Fleet / PromQL (VCF Ops 9.1) fleet certificates, password accounts, VCF domains, diagnostic findings, real-time PromQL query Read-only (5)

Total: 44 tools — 34 read-only, 10 write

Quick Start

# Install
uv tool install vmware-aria

# Configure
mkdir -p ~/.vmware-aria
cat > ~/.vmware-aria/config.yaml << 'EOF'
targets:
  prod:
    host: aria-ops.example.com
    username: admin
    port: 443
    verify_ssl: true
    auth_source: LOCAL
default_target: prod
EOF

# Set password (never in config.yaml)
echo "VMWARE_ARIA_PROD_PASSWORD=your_password" > ~/.vmware-aria/.env
chmod 600 ~/.vmware-aria/.env

# Verify setup
vmware-aria doctor

Offline / Air-Gapped Install (from source)

This project uses the modern PEP 517 build system (hatchling), so there is no setup.py by design — that is expected, not a missing file. If you cloned the source and hit ERROR: File "setup.py" or "setup.cfg" not found ... editable mode currently requires a setuptools-based build, your pip is older than 21.3 and cannot do an editable (-e) install with a non-setuptools backend. Editable mode is a developer convenience, not needed to run the tool — do one of:

# From the source tree — a normal (non-editable) install builds a wheel:
pip install .              # NOT  pip install -e .

# ...or upgrade pip first, and editable works too:
pip install --upgrade pip && pip install -e .

For a truly air-gapped host, build the wheels on a connected machine and copy them over — the target then needs no network:

# On a connected machine, collect this package + its dependencies as wheels:
pip wheel . -w dist        # → dist/*.whl   (or: uv build, for just this package)

# Copy dist/ to the air-gapped host, then install offline:
pip install --no-index --find-links dist vmware-aria

CLI Examples

# List top CPU consumers
vmware-aria resource top --metric 'cpu|usage_average' --top 10

# Check active CRITICAL alerts
vmware-aria alert list --criticality CRITICAL

# Acknowledge an alert
vmware-aria alert acknowledge <alert-id>

# Fetch 4-hour CPU + memory metrics for a VM ("missing" says why a key has no points)
vmware-aria resource metrics <vm-id> --metrics 'cpu|usage_average,mem|usage_average' --hours 4

# Check cluster capacity
vmware-aria capacity remaining <cluster-id>
vmware-aria capacity time-remaining <cluster-id>

# Find rightsizing opportunities (vCPU / memory now → recommended, direction, actionable)
vmware-aria capacity rightsizing

# Check Aria platform health: HEALTHY / DEGRADED / DOWN / UNKNOWN, per service, plus version
vmware-aria health status
vmware-aria health collectors

# Is the Aria node short of memory? Which adapter stopped collecting?
vmware-aria health node
vmware-aria health adapters

# Look up the metric keys a VM reports before querying them
vmware-aria resource keys <vm-id> --filter 'mem|'

# Put a host in maintenance for 2 hours before planned work, then end it (asks once; --dry-run prints the API call)
vmware-aria maintenance start <host-id> --duration 120
vmware-aria maintenance end <host-id>

# Record who is handling an alert, and read what Aria recommends
vmware-aria alert note-add <alert-id> "Taking this: rebooting esx-03"
vmware-aria alert recommendations <alert-id>

MCP Setup (Claude Code)

After uv tool install vmware-aria, add to ~/.claude.json:

{
  "mcpServers": {
    "vmware-aria": {
      "command": "vmware-aria",
      "args": ["mcp"],
      "env": {
        "VMWARE_ARIA_CONFIG": "~/.vmware-aria/config.yaml"
      }
    }
  }
}

v1.5.15+ uses the single-command form vmware-aria mcp. The legacy vmware-aria-mcp console script is still kept for backward compatibility. If you must use uvx --from vmware-aria vmware-aria mcp (no install) and hit invalid peer certificate: UnknownIssuer behind a corporate TLS proxy, set UV_NATIVE_TLS=true or use the recommended vmware-aria mcp form above.

Then use natural language:

  • "Show me the top 10 CPU consumers right now"
  • "List all CRITICAL alerts and acknowledge them"
  • "How long until the prod cluster runs out of memory?"
  • "Which VMs are over-provisioned? Show rightsizing recommendations"
  • "Are there any anomalies on vm-web-01?"

Authentication

Aria Operations uses vRealizeOpsToken authentication:

POST /suite-api/api/auth/token/acquire
{"username": "admin", "password": "...", "authSource": "LOCAL"}
→ {"token": "abc123", "validity": 1765182896000}  # validity = expiry epoch ms

Subsequent requests: Authorization: vRealizeOpsToken abc123

Tokens have a 6-hour sliding validity (extended on each call, per the official spec); the client re-acquires automatically 60 seconds before expiry. The validity field is the expiry timestamp in epoch milliseconds, not a duration.

Architecture

User (natural language)
  ↓
AI Agent (Claude Code / Goose / Cursor)
  ↓  [reads SKILL.md]
vmware-aria MCP server (stdio transport)
  ↓  [HTTPS + vRealizeOpsToken]
Aria Operations Suite API
  ↓
VMs / Hosts / Clusters / Alerts / Capacity

Companion Skills

Skill Scope Tools Install
vmware-aiops ⭐ entry point VM lifecycle, deployment, guest ops, clusters 60 uv tool install vmware-aiops
vmware-monitor Read-only monitoring, alarms, events, VM info 32 uv tool install vmware-monitor
vmware-nsx NSX networking: segments, gateways, NAT, IPAM 33 uv tool install vmware-nsx-mgmt
vmware-nsx-security DFW microsegmentation, security groups, Traceflow 22 uv tool install vmware-nsx-security
vmware-avi AVI / NSX ALB load balancing, AKO K8s operations 28 uv tool install vmware-avi
vmware-storage Datastores, iSCSI, vSAN 12 uv tool install vmware-storage
vmware-vks Tanzu Namespaces, TKC cluster lifecycle 23 uv tool install vmware-vks
vmware-harden Compliance baselines, drift detection 8 uv tool install vmware-harden

Security

  • Passwords loaded from env vars or .env file, never from config.yaml
  • Write operations (alert acknowledge/cancel, alert notes, alert definition management, report generate/delete, resource maintenance start/end) audit-logged to ~/.vmware/audit.db (MCP, via vmware-policy) and ~/.vmware-aria/audit.log (CLI)
  • API responses sanitized (control chars stripped, 500-char limit) to prevent prompt injection
  • TLS verification is on by default; for a private CA set SSL_CERT_FILE to a bundle with your CA (see setup guide). verify_ssl: false is for isolated self-signed labs only

Official Broadcom References

License

MIT — see LICENSE

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.15.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for zw008 from gravatar.com zw008

Credits

Author: Wei Zhou

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Tags

ai-ops aria capacity mcp monitoring vmware vrealize vrops

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vmware_aria-1.13.0.tar.gz (531.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

vmware_aria-1.13.0-py3-none-any.whl (171.1 kB view details)

Uploaded Python 3

File details

Details for the file vmware_aria-1.13.0.tar.gz.

File metadata

  • Download URL: vmware_aria-1.13.0.tar.gz
  • Upload date:
  • Size: 531.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.13.12

File hashes

Hashes for vmware_aria-1.13.0.tar.gz
Algorithm Hash digest
SHA256 b6ab735d5a440d1070e7abefb83bc8af54d0b953883305f412eb89573106c7bc
MD5 0fe378f22e364b24dd56d06ca6d0463f
BLAKE2b-256 e5a69c395a73a14fa6dd41ca9cfd1c221077c47ce52d5604a2cc3d25eac9abf3

See more details on using hashes here.

File details

Details for the file vmware_aria-1.13.0-py3-none-any.whl.

File metadata

  • Download URL: vmware_aria-1.13.0-py3-none-any.whl
  • Upload date:
  • Size: 171.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.13.12

File hashes

Hashes for vmware_aria-1.13.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8e15d5247740fdeecc5afcd548d96265b31ec3ac2f7a1d94fa81e87bf32509ab
MD5 3cf453187f6e2f91ae06bf290c511d1c
BLAKE2b-256 39ff2d7f860a7f645b9ace9454c7f58281db3965d8c00162e7e6d165068a47ce

See more details on using hashes here.

Release history Release notifications | RSS feed

1.15.0

2 files

1.14.1

2 files

1.14.0

2 files

This release

1.13.0 This release

2 files

1.12.0

2 files

1.11.0

2 files

1.10.0

2 files

1.9.1

2 files

1.9.0

2 files

1.8.15

2 files

1.8.14

2 files

1.8.13

2 files

1.8.12

2 files

1.8.11

2 files

1.8.10

2 files

1.8.9

2 files

1.8.8

2 files

1.8.7

2 files

1.8.5

2 files

1.8.4

2 files

1.8.3

2 files

1.8.2

2 files

1.8.1

2 files

1.8.0

2 files

1.7.5

2 files

1.7.4

2 files

1.7.3

2 files

1.7.2

2 files

1.7.1

2 files

1.7.0

2 files

1.6.1

2 files

1.6.0

2 files

1.5.39

2 files

1.5.38

2 files

1.5.37

2 files

1.5.36

2 files

1.5.35

2 files

1.5.34

2 files

1.5.33

2 files

1.5.32

2 files

1.5.31

2 files

1.5.30

2 files

1.5.29

2 files

1.5.28

2 files

1.5.27

2 files

1.5.26

2 files

1.5.23

2 files

1.5.22

2 files

1.5.21

2 files

1.5.20

2 files

1.5.19

2 files

1.5.18

1 file

1.5.17

2 files

1.5.16

2 files

1.5.15

2 files

1.5.14

2 files

1.5.13

2 files

1.5.12

2 files

1.5.11

2 files

1.5.10

2 files

1.5.8

2 files

1.5.7

2 files

1.5.6

2 files

1.5.5

2 files

1.5.4

2 files

1.5.3

2 files

1.5.0

2 files

1.4.9

2 files

1.4.8

2 files

1.4.7

2 files

1.4.6

2 files

1.4.5

2 files

1.4.4

2 files

1.4.3

2 files

1.4.1

2 files

1.4.0

2 files

1.3.5

2 files

1.3.4

2 files

1.3.3

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page