netlab-mcp

An MCP server that wraps ipspace/netlab as an engine to give LLMs access to validated, lab-tested network device configurations — instead of hallucinated ones.

Why

Getting working network configs out of a raw LLM is unreliable: vendor-syntax drift, no validation, invented data-model fields, no interop guarantees. netlab already solves the hard part — it owns the data-model transform (AS / RD-RT / VNI / neighbor computation), the Jinja2 render, the containerlab provider, and a netlab validate test system. This server does not re-serve raw .j2 templates or rebuild that pipeline. It exposes netlab's outputs to an LLM and records what actually passes in a lab.

What it does

• Offline (fast, no docker): translate intent → netlab topology, render real per-device config, query declared module/platform support.
• Lab (needs docker + containerlab): deploy to containerlab, run netlab validate, record the pass/fail verdict into a version-scoped compatibility matrix.

[!WARNING] Lab ≠ production. Every config-bearing tool response embeds the full disclaimer from netlab_mcp.models.DISCLAIMER. Configs are validated only in an isolated, synthetic netlab + containerlab lab on free images. "Validated in lab" ≠ "safe in your network" — review IP/AS/naming and interactions with your existing config before applying to real gear. See SECURITY.md.

Scope (MVP)

• Free containerlab images only: srlinux, frr, cumulus, vyos, linux (ceos behind an explicit EULA env flag). Licensed NOSes (nxos/iosxr/sros/junos/…) come later behind a self-hosted runner.
• First proven loop: eBGP across srlinux + frr.

Tools

Tool	Mode	Disclaimer	Purpose
generate_topology	offline	—	intent + platforms → netlab topology YAML (validated by parse)
render_config	offline	✅	topology → real per-device config + clab.yml
query_compatibility	offline	—	netlab declared support, overlaid with observed lab verdicts
get_known_good	offline	✅	return a previously lab-passed topology + config
list_examples	offline	—	index netlab's integration test topologies
report_failure	offline	—	record a negative result into the matrix
validate_in_lab	lab	✅	deploy + netlab validate + record verdict

Mode: offline needs no docker; lab requires docker + containerlab. Disclaimer: ✅ responses embed the lab≠production disclaimer.

Install — offline (no docker)

The engine (netlab binary + netsim) installs from PyPI as networklab; you do not need to vendor it.

uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install -e '.[dev]'          # pulls networklab (the `netlab` binary) from PyPI

# Only `list_examples` needs netlab's SOURCE tree (tests/integration); it is gitignored.
git clone --depth 1 https://github.com/ipspace/netlab netlab

pytest -m "not docker"              # offline + contract suite, no docker needed
netlab-mcp                          # run the MCP server over stdio

Install — lab (docker + containerlab)

The lab path (validate_in_lab) has host prerequisites that pip does not install. On a dedicated Linux lab host:

#	Prerequisite	Why	How
1	containerlab ≥ 0.75.0	netlab 26.06's container provider requires it	containerlab install docs
2	Ansible in the same venv as netlab	netlab pushes device config via Ansible, calling bare ansible-galaxy/ansible-playbook from PATH	uv pip install 'ansible<=11.10' paramiko netmiko ansible-pylibssh ncclient netaddr (or netlab install ansible)
3	Per-device Ansible collections	each NOS driver needs its collection	e.g. ansible-galaxy collection install nokia.srlinux (srlinux); arista.eos (ceos)
4	Scoped passwordless sudo for containerlab	netlab runs sudo -E containerlab deploy non-interactively	see block below

PATH trap: because netlab invokes bare binary names, the server must run with the venv activated (or .venv/bin on PATH), or netlab won't find ansible-playbook / netlab.

Passwordless sudo — create /etc/sudoers.d/netlab-clab (mode 0440, validate with visudo -cf):

<user> ALL=(root) NOPASSWD: SETENV: /usr/bin/containerlab

• The SETENV: tag is mandatory — netlab passes -E; without it you get sorry, you are not allowed to preserve the environment.
• Do NOT use NOPASSWD: ALL.
• Security implication: containerlab can bind-mount host paths and run privileged containers, so this entry is effectively passwordless root for <user>. Use it only on a dedicated/disposable lab host. See SECURITY.md.

Verify the host is lab-ready: docker info and containerlab version (≥ 0.75.0) succeed. If they don't, validate_in_lab degrades cleanly to verdict unavailable (it is not an error) and the offline tools keep working.

Quickstart — the eBGP srlinux + frr loop

Canonical topology: tests/fixtures/mvp_bgp.yml — srlinux DUT (AS 65000) ↔ frr peer (AS 65100), with a validate.session test that checks the BGP neighbor reaches Established.

Driving the tools the way an MCP client would (see scripts/smoke_offline.py):

1. generate_topology("ebgp peering", ["srlinux", "frr"]) → netlab topology YAML.
2. render_config(topology_yaml) → real per-node config (srlinux JSON-RPC, frr vtysh) + clab.yml.
3. validate_in_lab(topology_yaml, ["srlinux", "frr"], module="bgp") → deploy + netlab validate; verdict pass is recorded as known-good (with cached artifacts).
4. get_known_good("bgp", "srlinux") → the lab-passed topology + config for reuse.

Security model

• Free-image allow-list, enforced on netlab's resolved node devices (not the caller's platforms claim) and fails closed when a device can't be resolved — licensed NOSes are rejected.
• ceos is gated behind the explicit NETLAB_MCP_ACCEPT_CEOS_EULA env flag.
• External tools: (edgeshark, nso, …) are rejected, with netlab up --no-tools as a backstop.
• A platforms/topology mismatch is rejected (no spoofing the declared device set).
• Every config-bearing response embeds the lab≠production disclaimer.

Full threat model — including what the guardrails explicitly do not protect against — is in SECURITY.md.

Configuration (env vars)

Variable	Effect
NETLAB_MCP_NETLAB_BIN	path to the netlab executable (default: same venv, then PATH)
NETLAB_MCP_STORE	store dir for the matrix db + artifacts (default: ./store)
NETLAB_MCP_WORKDIR	base dir for per-request temp workdirs (default: ./.work)
NETLAB_MCP_ACCEPT_CEOS_EULA	set truthy to allow the EULA-gated ceos image

Architecture

LLM / MCP client → FastMCP server (allow-list + disclaimer guardrails) → offline engine (netlab create / initial -o / show module-support) or lab engine (netlab up → containerlab → netlab validate) → sqlite matrix store. See docs/netlab-mcp-architecture.excalidraw (open at excalidraw.com → File ▸ Open; regenerate with python scripts/gen_diagram.py).

Layout

src/netlab_mcp/
  server.py            FastMCP app + tool registrations
  config.py            netlab binary discovery, platform allow-list, paths
  models.py            disclaimer + shared constants
  engine/              runner, transform, render, compat, probes, lab, topo, topogen
  store/               sqlite matrix + yaml mirror + results.yaml harvest
store/                 runtime state (matrix.db gitignored, matrix.yaml committed)
tests/                 offline (CI-safe), contract, lab (docker-gated)

Contributing

See CONTRIBUTING.md. The PR gate is pytest -m "not docker"; lab tests are docker-gated. By participating you agree to the Code of Conduct.

License

Apache-2.0. The wrapped ipspace/netlab engine is separately licensed (MIT) and is not vendored or redistributed by this project — it is installed as a dependency.

Acknowledgements

Built on ipspace/netlab and containerlab. Disclaimer: this is an independent project, not affiliated with or endorsed by either.