clab-mcp

Two MCP servers that let Claude build, deploy and verify containerlab network topologies on macOS — from a plain-English sentence.

build me a 2-spine 4-leaf EVPN fabric with VNI 10010

Claude turns that into a complete topology: loopbacks, /31 fabric addressing, OSPF areas, BGP EVPN peerings to every route reflector, per-leaf bridge and VXLAN devices, host attachment — then deploys it and walks the verification chain from OSPF adjacency down to a packet capture of the VXLAN header.

Full setup and usage runbook: SETUP.md

How it works

containerlab is a Linux program — netlink, network namespaces, veth pairs. On macOS it runs inside a Linux VM. These servers run on macOS and reach into that VM with orb -m <vm>.

macOS
├── Claude Desktop
│    ├── clab-builder  ── writes topology + config files ──┐
│    └── clab-lab  ── orb -m clab ──┐                      │
└── OrbStack                        │                      │
     └── Linux VM "clab"  <─────────┘                      │
          ├── containerlab + docker                        │
          └── frr containers  <──────── files synced ──────┘

The split is deliberate:

• clab-builder only writes files. No OrbStack, no containerlab, no network access. It cannot break a running lab.

• clab-lab is the only thing that runs containerlab.

Related MCP server: netlab-mcp

Requirements

• macOS (Apple Silicon or Intel)

• Claude Desktop

• Python 3.10+

• OrbStack with a Linux machine (default name clab) running Docker and containerlab

Setting up the VM itself is out of scope — SETUP.md Stage 0 verifies it rather than installing it.

Install

git clone https://github.com/<your-username>/clab-mcp.git ~/clab-mcp
cd ~/clab-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
bash register.sh

register.sh runs preflight checks, backs up your Claude Desktop config with a timestamp, then merges two entries into mcpServers — existing servers and other top-level keys are untouched. Re-running only updates the two entries.

Then quit Claude Desktop with Cmd + Q (closing the window leaves the old processes running) and reopen it.

Verify by asking Claude to run clab_env.

Configuration

Pass any of them to register.sh and they are written into the config entries:

CLAB_VM=mylab CLAB_MAC_DIR=~/my-labs bash register.sh

Tools

clab-builder — generates topologies

clab-lab — deploys and inspects

The fabric spec

Every key except lab has a default:

lab: evpn-vxlan
spines: 2
leaves: 4
underlay: ospf          # ospf (iBGP + route reflector) | ebgp (per-device ASN)
overlay: evpn           # evpn | none
asn: 65000
route_reflectors: [spine1, spine2]
spine_loopbacks: 10.255.0.0/24
leaf_loopbacks: 10.255.1.0/24
p2p: 10.0.0.0/24
fabric_mtu: 9100
vnis:
  - {vni: 10010, vlan: 10}
hosts:
  - {name: pc1, leaf: leaf1, vni: 10010, ip: 192.168.10.11/24}
  - {name: pc2, leaf: leaf2, vni: 10010, ip: 192.168.10.22/24}

Change spines: and leaves: and the addressing, interface numbering, OSPF, BGP peerings and per-leaf VXLAN devices are all recomputed.

What validate_lab catches

The failures that leave a fabric looking healthy while passing no traffic:

• an interface used by two links, or an endpoint naming a node that does not exist

• a /31 pair whose two ends are not actually on the same subnet

• a BGP neighbour address matching no configured loopback or link address

• a VXLAN device sourced from an IP that is not that leaf's own loopback

• a VTEP whose BGP is missing advertise-all-vni

• an access port joined to a bridge that is not a real link

• the loopback address set after the VXLAN device is created

• bgpd/ospfd disabled in daemons while the config uses them

• eBGP without no bgp ebgp-requires-policy — FRR 7.4+ silently drops everything

• an eBGP EVPN spine missing retain route-target all, or rewriting the VTEP next-hop

Coverage and limits

• underlay: ospf + overlay: evpn is the validated path — deployed and verified end to end including a packet capture of the VXLAN header.

• underlay: ebgp generates the standard eBGP-CLOS-with-EVPN pattern and passes every static check, but has not been deployed on a live fabric.

• L2VNI only. No L3VNI, no tenant VRF, no anycast gateway — hosts sharing a VNI must share a subnet.

• FRR only. SR Linux nodes can be added with add_node, but build_fabric does not generate SR Linux configs.

• Images used are arm64-native and login-free: FRRouting and network-multitool.

License

MIT — see LICENSE.