ContainerLab Lab Management

MCP Server

• Command: python3 -u $CLAB_MCP_SCRIPT (stdio transport)
• Requires: CLAB_API_SERVER_URL, CLAB_API_USERNAME, CLAB_API_PASSWORD environment variables
• Auto-authentication: Every tool call auto-authenticates — no explicit authenticate call needed

How to Call Tools

bash
python3 $MCP_CALL "python3 -u $CLAB_MCP_SCRIPT" <tool_name> '<args_json>'

Available Tools

| Tool | Parameters | What It Does | |------|-----------|-------------| | authenticate | apiServerURL, username, password | Manual auth override (optional — auto-auth handles normal usage) | | listLabs | none | List all labs on the ContainerLab server | | deployLab | topologyContent (JSON object), reconfigure (bool) | Deploy a new lab topology | | inspectLab | labName, details (bool) | Get lab details, node status, management IPs | | execCommand | labName, command, nodeName (optional) | Execute a command on one or all nodes | | destroyLab | labName, cleanup (bool), graceful (bool) | Destroy a lab and clean up resources |

Workflow: Deploy a New Lab

When a user wants to create a containerized network lab:

1. List existing labs: listLabs — check what's already running, avoid name conflicts
2. Deploy topology: deployLab with a topology JSON object
3. Inspect lab: inspectLab with details: true — verify success, get management IPs
4. Execute commands: execCommand — run show commands to verify connectivity
5. Report back: Tell the user the lab is ready with node names and management IPs

Example: 2-Node SR Linux Lab

bash
# List existing labs
python3 $MCP_CALL "python3 -u $CLAB_MCP_SCRIPT" listLabs '{}'

# Deploy
python3 $MCP_CALL "python3 -u $CLAB_MCP_SCRIPT" deployLab '{"topologyContent":{"name":"srlinux-demo","topology":{"nodes":{"srl1":{"kind":"nokia_srlinux","image":"ghcr.io/nokia/srlinux:latest","type":"ixrd2l"},"srl2":{"kind":"nokia_srlinux","image":"ghcr.io/nokia/srlinux:latest","type":"ixrd2l"}},"links":[{"endpoints":["srl1:e1-1","srl2:e1-1"]},{"endpoints":["srl1:e1-2","srl2:e1-2"]}]}}}'

# Inspect
python3 $MCP_CALL "python3 -u $CLAB_MCP_SCRIPT" inspectLab '{"labName":"srlinux-demo","details":true}'

# Execute command
python3 $MCP_CALL "python3 -u $CLAB_MCP_SCRIPT" execCommand '{"labName":"srlinux-demo","nodeName":"srl1","command":"show version"}'

Workflow: Lab Cleanup

When a user is done with a lab:

1. Confirm with user: Ask before destroying
2. Destroy lab: destroyLab with graceful: true and cleanup: true
3. Record in GAIT: Log the destruction for audit trail

bash
python3 $MCP_CALL "python3 -u $CLAB_MCP_SCRIPT" destroyLab '{"labName":"srlinux-demo","cleanup":true,"graceful":true}'

Topology Design Guidance

ContainerLab topologies define nodes and links in a structured JSON format.

Supported Node Kinds

ContainerLab supports a wide range of network operating systems:

| Kind | Platform | Example Image | |------|----------|---------------| | cisco_iosxr | Cisco IOS XR | ios-xr/xrd-control-plane:latest | | cisco_iosxe | Cisco IOS XE (Cat8000v) | c8000v:latest | | cisco_nxos | Cisco NX-OS (Nexus 9000v) | n9kv:latest | | cisco_ftdv | Cisco Firepower FTDv | ftdv:latest | | nokia_srlinux | Nokia SR Linux | ghcr.io/nokia/srlinux:latest | | ceos | Arista cEOS | ceos:latest | | juniper_crpd | Juniper cRPD | crpd:latest | | frr | FRRouting | frrouting/frr:latest | | linux | Generic Linux | alpine:latest |

For the full list, see the ContainerLab documentation.

Basic Topology Structure

json
{
  "name": "lab-name",
  "topology": {
    "nodes": {
      "node1": {
        "kind": "nokia_srlinux",
        "image": "ghcr.io/nokia/srlinux:latest"
      },
      "node2": {
        "kind": "nokia_srlinux",
        "image": "ghcr.io/nokia/srlinux:latest"
      }
    },
    "links": [
      {"endpoints": ["node1:e1-1", "node2:e1-1"]}
    ]
  }
}

Common Lab Patterns

Multi-vendor lab:

"Deploy a 4-node lab:
- 2 x SR Linux switches (leaf1, leaf2)
- 1 x FRR router (spine1)
- 1 x Linux host (client1)
- leaf1 and leaf2 connected to spine1
- client1 connected to leaf1"

Spine-leaf fabric:

"Build a 2-spine, 4-leaf SR Linux fabric:
- Full mesh between spines and leaves
- iBGP between all nodes"

Integration with Other Skills

• Use gait-session-tracking to record all lab operations in the audit trail
• Use markmap-viz to visualize lab topologies as interactive mind maps
• Use drawio-diagram for lab network diagrams

Important Rules

• Lab-only operations — ContainerLab operations are lab-only. No ServiceNow CR gating required
• GAIT audit mandatory — Record all lab operations in the GAIT audit trail
• List before deploy — Always list existing labs before deploying to avoid name conflicts
• Inspect after deploy — Always inspect after deployment to verify success and get management IPs
• Graceful shutdown — Use graceful: true when destroying labs for clean node shutdown
• Docker restart — If the ContainerLab API server runs in Docker and auth fails, the container may need a restart to pick up new Linux users

Error Handling

• Auth fails (401): Check CLAB_API_SERVER_URL, CLAB_API_USERNAME, CLAB_API_PASSWORD in ~/.openclaw/.env. If the API server runs in Docker, restart the container after creating the Linux user
• Deploy fails: Check topology syntax — nodes must have valid kind and image fields. Use listLabs to check for name conflicts
• Exec fails: Verify the lab is deployed via inspectLab. Check node name is correct
• Destroy fails: Verify lab name via listLabs. If graceful shutdown times out, retry without graceful: true

Environment Variables

• CLAB_API_SERVER_URL — ContainerLab API server URL (e.g., http://localhost:8080)
• CLAB_API_USERNAME — API username (default: netclaw)
• CLAB_API_PASSWORD — API password
• CLAB_MCP_SCRIPT — Path to the Python MCP server script (set by install.sh)
• MCP_CALL — Path to mcp-call.py wrapper (set by install.sh)