Nvidia Cumulus

MCP server that integrates with the Cumulus Linux OS. This application was implemented using FastMCP and NVIDIA's NVUE API.

[!NOTE] This application was developed for Cumulus VX (Virtual Experience) 5.4.0. It has not been tested on actual hardware or the latest version since the simulator has since migrated to the NVIDIA AIR cloud sandbox.

flowchart LR
    user["User / MCP client"]
    server["nvidia-cumulus-nvue<br/>FastMCP server"]
    tools["Read-only MCP tools<br/>platform, system, interfaces, VRFs, BGP"]
    client["NVUEClient<br/>HTTP GET + basic auth"]
    cumulus["Cumulus VX or switch<br/>NVUE API /nvue_v1"]

    user -- "MCP over stdio" --> server
    server --> tools
    tools --> client
    client -- "HTTPS GET :8765" --> cumulus
    cumulus -- "JSON response" --> client
    client --> tools
    tools --> server
    server -- "tool result" --> user

Quick Start

Configuring a simulator (optional)

You can find a copy of Cumulus VX by downloading the qcow2 file from GNS3. Run the simulator and be sure to forward ports for SSH and the NVUE API

qemu-system-x86_64 \
  -enable-kvm \
  -m 2048M \
  -smp 2 \
  -hda cumulus-linux-5.4.0-vx-amd64-qemu.qcow2 \
  -netdev user,id=mgmt,hostfwd=tcp:0.0.0.0:2222-:22,hostfwd=tcp:0.0.0.0:8765-:8765 \
  -device virtio-net-pci,netdev=mgmt \
  -nographic

By default the OS will have services like ssh and nginx enabled. In order to get the NVUE API connection to work, you need to modify your nginx config:

sudo ln -s /etc/nginx/sites-{available,enabled}/nvue.conf
sudo sed -i 's/listen localhost:8765 ssl;/listen 0.0.0.0:8765 ssl;/g' /etc/nginx/sites-available/nvue.conf
sudo systemctl restart nginx

You can confirm that this API is reachable from your host machine by doing

curl -u '<username>:<password>' -k https://localhost:8765/nvue_v1/interface

Configuring the target machine

Once you have a simulator or an actual switch to use you can run the MCP by doing:

uv sync
export CUMULUS_HOST=127.0.0.1
export CUMULUS_PORT=8765
export CUMULUS_USERNAME=cumulus
export CUMULUS_PASSWORD=cumulus100
export CUMULUS_VERIFY_TLS=false
uv run nvidia-cumulus-mcp

Alternatively, you can add the MCP config:

{
  "mcpServers": {
    "nvidia-cumulus-nvue": {
      "command": "uv",
      "args": ["run", "nvidia-cumulus-mcp"],
      "env": {
        "CUMULUS_HOST": "127.0.0.1",
        "CUMULUS_PORT": "8765",
        "CUMULUS_USERNAME": "cumulus",
        "CUMULUS_PASSWORD": "cumulus100",
        "CUMULUS_VERIFY_TLS": "false"
      }
    }
  }
}

Configuration

Variable	Default	Description
CUMULUS_HOST	127.0.0.1	Cumulus VX or switch hostname/IP
CUMULUS_PORT	8765	NVUE API HTTPS port
CUMULUS_USERNAME	cumulus	NVUE basic-auth username
CUMULUS_PASSWORD	required	NVUE basic-auth password
CUMULUS_VERIFY_TLS	false	Enable TLS certificate validation
CUMULUS_CA_BUNDLE	unset	Optional CA bundle path for TLS validation
CUMULUS_TIMEOUT	10	HTTP timeout in seconds

Tools

All tools are read-only and return:

{
  "endpoint": "/nvue/path",
  "data": {}
}

Available tools:

• nvue_get(path, include=None, omit=None, rev=None)
• get_platform()
• get_system()
• get_system_resources()
• list_interfaces()
• get_interface(interface)
• get_interface_counters(interface)
• list_bridges()
• get_bridge(domain="br_default")
• get_mac_table(domain="br_default")
• list_vrfs()
• get_vrf(vrf="default")
• get_routes(vrf="default", afi=None)
• get_ip_neighbors(interface, family="all")
• get_lldp_neighbors(interface)
• get_bgp_global()
• get_bgp_vrf(vrf="default")
• get_bgp_neighbors(vrf="default")

Development

uv sync
.venv/bin/pytest
.venv/bin/ruff check .
.venv/bin/mypy

Live integration tests are opt-in and only issue NVUE GET requests:

RUN_CUMULUS_INTEGRATION=1 \
CUMULUS_HOST=127.0.0.1 \
CUMULUS_USERNAME=cumulus \
CUMULUS_PASSWORD=cumulus100 \
.venv/bin/pytest tests/test_integration_live.py

References

• NVIDIA Cumulus Linux 5.4 NVUE API: https://docs.nvidia.com/networking-ethernet-software/cumulus-linux-54/System-Configuration/NVIDIA-User-Experience-NVUE/NVUE-API/
• NVIDIA Cumulus Linux 5.4 OpenAPI specification: https://docs.nvidia.com/networking-ethernet-software/cumulus-linux-54/api/openapi.json
• FastMCP tools: https://gofastmcp.com/servers/tools