# NVIDIA Cumulus MCP Server

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. 


```mermaid
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](https://www.gns3.com/marketplace/appliances/cumulus-vx). Run the simulator and be sure to forward ports for SSH and the NVUE API

```bash
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:

```bash
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

```bash
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:

```bash
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:

```json
{
  "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:

```json
{
  "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

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

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

```bash
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>