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.

Related MCP server: EVE-NG MCP Server

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.

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

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:

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)

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.