Network Lab MCP

An AI Network Engineer Workspace for real network labs.

Why I built it

I work as a network engineer, and I often find myself wanting to validate something in a lab but simply not having enough time to do it. Customer work, troubleshooting, meetings, documentation, and many other tasks usually come first. The lab work is important, but it is also time-consuming.

That made me wonder: what if I could ask AI to do the lab investigation for me? Not just run a command, but understand the topology, connect to the right devices, inspect the current state, compare results, investigate problems, and report back with evidence.

At the same time, I did not want the AI to become a black box. As a network engineer, I still want to see what it is doing and make the final engineering decisions.

Network Lab MCP is the result: a thin foundation that lets Claude Code (or any other MCP client) understand a lab's topology, follow common operating principles, understand the current task, draw on reusable reference knowledge, and reach lab devices through a real terminal — while every terminal session stays human-observable, and every actual network engineering decision stays with the engineer.

Related MCP server: MCP-Telecom

What it does

Network Lab MCP is not a fixed test-automation tool, and it is not a network-engineering reasoning engine. It gives an MCP client two things:

1. Lab knowledge — where the work happens, how to behave, what to accomplish, and what reusable knowledge already exists.

2. Terminal access — a real, general-purpose way to interact with lab devices, close to how a human operator would use a terminal, without ever handing the AI the private connection details.

All actual network engineering judgment — what command to run next, how to interpret output, when a task is done — is left to Claude Code.

It also includes an independent, IOS XR-compatible human-facing CLI (./run_cli.sh) for creating and editing lab definitions (topology, private access information, scenario, reference) through a candidate/commit model, and for observing terminal activity live while the AI works.

How it works

Claude Code                          Human Operator
    |                                     |
Network Lab MCP (this repository)   ./run_cli.sh (this repository)
    |                                     |
dedicated tmux environment           Candidate configuration -> commit
(socket: network-lab-mcp)                 |
    |                                Committed lab YAML
ssh / telnet                              |  (running-config, topology,
    |                                     |   access-info, scenario, reference)
Lab Devices                          (read by Network Lab MCP above)

Five kinds of lab data are deliberately kept separate:

access-info  = HOW TO ACCESS DEVICES     = private, never sent to Claude
topology     = WHAT EXISTS / CONNECTIVITY = safe, sent to Claude
scenario     = WHAT TO DO                 = sent to Claude
reference    = REUSABLE KNOWLEDGE         = sent to Claude
running-config = WHICH topology/scenario/references MCP uses right now

running-config is a selection, not a definition: it never contains device data itself, only the names of the topology/scenario/references currently in effect. Topology/access-info/scenario/reference are definitions: each one is a named, independently authored/edited YAML document. Editing a definition (e.g. topology lab1 in the CLI) never changes which definition MCP currently uses; only committing a running-config change does that.

Placed alongside Principles, Terminal, Claude Code, and Workspace, the full responsibility model looks like this:

The Workspace is deliberately not managed by Network Lab MCP: Claude Code uses its own current working directory (the task workspace it was started from) to store evidence, configurations, and reports, organized however the task requires. See docs/architecture.md for the full picture, including the device-access resolution flow.

Key design principles

• Exactly seven MCP tools, and nothing else. get_active_topology, get_execution_instructions, terminal_open, terminal_send, terminal_read, terminal_list, terminal_close. There is no batch/ parallel tool, no config-mutation tool, and no tool that returns access-info. See docs/mcp_tools.md.

• Real, human-observable terminals. Terminal sessions run in a dedicated tmux environment, driven the same way a human operator would drive one: read the pane, decide what to send, send it. Nothing here parses device prompts or maintains a device-CLI state machine — Claude Code does that reasoning itself. A human can watch the exact same session live with monitor terminal <device>.

• Private access-info, never exposed to Claude. Device addresses, usernames, and passwords live in a separate access-info definition that no MCP tool ever returns. terminal_open(device) receives only a logical device name; Network Lab MCP resolves the private connection details itself.

• Candidate/commit configuration, IOS XR-style. The human CLI edits lab definitions and the running-config selection through a candidate → commit model — nothing is written to disk, and nothing is visible to Claude Code, until an explicit commit succeeds.

• Discovery is candidate-first, never automatic. discover topology populates a topology candidate for human review; it never auto-commits and never auto-selects the result as the active topology.

• Fail closed, not silently guessed. A missing access-info selection, an unresolvable device, a device-type mismatch between topology and access-info, an ambiguous Discovery neighbor — every one of these is a clear, sanitized error rather than a guess.

Quick Start

Prerequisites

• Linux (developed and validated here). Likely compatible with macOS, since it depends only on tmux/OpenSSH/a POSIX shell, but that has not been formally validated in this project. Native Windows is not supported — tmux has no native Windows build (WSL2, which provides a real Linux environment, should work but has not been formally validated either).

• Python 3.10 or newer (see pyproject.toml's requires-python).

• tmux — the terminal session backbone; every managed session depends on it.

• An OpenSSH client (ssh) — required for any transport: ssh device.

• A telnet client — only required if any device uses transport: telnet.

• An MCP-capable client, such as Claude Code.

cd ~/work/network-lab-mcp

python3 -m venv .venv
source .venv/bin/activate

pip install -e .

Register the server once, from anywhere, after installing it into an activated environment:

claude mcp add --scope user --transport stdio network-lab -- network-lab-mcp

(Verified against Claude Code CLI 2.1.277's claude mcp add --help; if a newer Claude Code version changes this syntax, follow its own --help output instead of this snippet.)

--scope user registers the server for the current user across all projects. network-lab-mcp must be resolvable on PATH at the time Claude Code launches it — for example, by installing it into an environment that is active in your shell, or by using that environment's absolute path in place of network-lab-mcp.

Set up your local running-config selection once:

cp lab/settings.example.yaml lab/settings.yaml

Then start Claude Code from whatever task workspace you like (it does not need to be this repository):

cd ~/work/customer-lab-investigation
claude

Network Lab MCP does not depend on that working directory. One Network Lab MCP checkout owns exactly one lab root, and that lab root can contain multiple topologies, access-info definitions, scenarios, and references; lab/settings.yaml selects which topology/scenario/references are currently in effect.

Advanced / isolated-lab-only: some workflows run Claude Code with claude --permission-mode bypassPermissions to avoid per-command approval prompts. This skips Claude Code's own safety confirmations entirely and is only appropriate in an isolated lab environment you fully control — you are assuming that risk yourself. It is not the normal or recommended way to run Claude Code against this project.

Run the human configuration CLI to review or edit lab definitions:

./run_cli.sh
network-lab#

Run help inside it for a Quick Start covering the typical configuration workflow, and help claude for how Claude Code uses Network Lab MCP.

Supported installation model

Network Lab MCP supports exactly one deployment model: a local repository checkout, installed with pip install -e .. The repository checkout owns the lab/ directory, and the MCP server resolves it relative to its own source location — never relative to the current working directory of whatever process launched it. pip install ., installing from a built wheel, or pip install network-lab-mcp from a package index are not supported — lab/ is repository-local operational data, not a Python package resource, so a non-editable install has no lab directory to find.

Example workflow

The tracked sample.yaml files use RFC 5737 documentation-only addresses, which are not reachable — Discovery cannot actually connect to them. For real Discovery/terminal access, create your own private access-info first (never edit the tracked sample directly):

cp lab/access-info/sample.yaml lab/access-info/my_lab.yaml
# edit lab/access-info/my_lab.yaml with your real device addresses and
# credentials, then select it: running-config's `access-info my_lab`

The transcript below is illustrative output from a configured, reachable lab (not the tracked sample environment) — access-info name, target counts, and observation counts will differ for your own lab:

network-lab# configure
network-lab(config)# discover topology
Discovering topology from access-info 'my_lab'...
Discovery complete.

  Access-info:          my_lab
  IOS XR targets:       2
  IOS XE targets:       0
  IOS targets:          0
  Connected:            2
  LLDP observations:    4
  CDP observations:     0
  Managed links:        2
  Unresolved neighbors: 0
  L3 enrichment:        2/2 devices, 2 interfaces
  Topology candidate:   my_lab

network-lab(config-topology-my_lab)# show configuration
...
network-lab(config-topology-my_lab)# commit
Commit complete.
network-lab(config-topology-my_lab)# root
network-lab(config)# running-config
network-lab(config-running)# topology my_lab
network-lab(config-running)# commit
Commit complete.

get_active_topology() (and every other MCP tool) keeps returning the previously active topology until that final explicit running-config topology/commit step — Discovery's own commit only persists the topology definition, never the active selection.

From there, a typical Claude Code session calls get_active_topology() and get_execution_instructions() to learn where to work and what to accomplish, then terminal_open()/terminal_send()/terminal_read() to investigate the devices that matter for the task, reporting back with evidence saved in its own task workspace.

Human-observable terminals

Because every session lives in a dedicated tmux environment, an engineer can watch exactly what the AI is doing, live, without interfering with it:

network-lab# monitor terminal R1
RP/0/RP0/CPU0:R1#show version
...
RP/0/RP0/CPU0:R1#

--------------------------------------------------------------------------------
Monitoring terminal R1 | Read-only | Source: managed | Status: active | q: quit
--------------------------------------------------------------------------------

monitor terminal <device-id> (EXEC-only, strictly read-only) streams the currently preferred terminal session's activity into the local terminal while keeping a live status bar at the bottom — everything it prints stays in the terminal emulator's own scrollback, exactly like ordinary command output. It prefers a normal managed session, falling back to an active Discovery bootstrap session when no managed session exists yet, and several independent monitors (of the same or different devices) can run at once from separate ./run_cli.sh windows. See "monitor terminal" in the CLI reference for the full behavior.

Historical evidence does not depend on the monitor being open: every device session, managed or Discovery, is also captured to a persistent per-session log file (logs/terminal/<device-id>/*.log), reviewable with show logging — see docs/cli_reference.md.

Security model

Credentials never reach the AI

Real access-info YAML stores device usernames and passwords directly (this is a lab tool; it does not introduce a separate secret store). Credentials are used only to drive interactive terminal login. Network Lab MCP:

• never returns access-info from any MCP tool: get_active_topology() returns only the safe topology, and get_execution_instructions() never includes it either;

• never logs passwords or terminal_send() input text, and never echoes that input text back in tool responses;

• never includes credentials in generated documentation or error messages;

• never persists credentials into any separate runtime database — tmux is the only session state, and there isn't a second one.

terminal_open(device) receives only a logical device name from Claude — never an address, username, or password. Network Lab MCP resolves the private connection details itself:

1. Read the committed running-config and resolve the active topology.

2. Verify the device exists in the active topology.

3. Resolve the running-config's selected access-info (active_access_info) — fail closed if none is selected, or if the selected definition does not exist on disk.

4. Load only that one access-info definition and look up the device in it — fail closed if it is absent. No other access-info file is ever searched.

5. If both the topology and the resolved access-info specify type, normalize both through the shared device-type enum and compare — fail closed on a mismatch.

6. If the device has an optional jump_host reference, resolve it within the same access-info definition and attach it for a single-hop OpenSSH ProxyJump connection (see "Single-hop SSH jump hosts" below); otherwise connect directly.

7. Only then does the tmux/ssh/telnet path run. Once the session exists, terminal_open() also completes private target authentication if the target's own login prompt actually appears — see "Private managed-terminal authentication" below.

Selecting which access-info definition this resolution reads is done through running-config's access-info <name> / no access-info — the same candidate/commit model as topology/scenario/reference selection, and just as invisible to terminal_open() until committed.

Private managed-terminal authentication

Network Lab MCP can complete target authentication for a managed terminal over either transport, using the selected private access-info definition — SSH password authentication, or classic-IOS-style Telnet username/password login. Credentials remain inside Network Lab MCP and are not exposed to the AI/MCP client:

Claude
   |
   | terminal_open(R1)
   v
Network Lab MCP
   |
   +--> committed active access-info
   |        |
   |        +--> private username/password
   |
   v
native SSH/Telnet in tmux
   |
   +--> verify target login prompt (SSH password prompt, or Telnet
   |    Username:/Password:)
   |
   +--> send credentials privately, via a stdin-based tmux buffer paste --
   |    never as a command-line argument to any process
   |
   v
authenticated terminal

Neither transport's credentials ever cross the MCP boundary, appear in any process's command-line arguments, or appear in an exception message. terminal_open() recognizes only OpenSSH's own client-side password prompt for SSH (never a device-CLI-specific prompt, so this works for every device type, not just IOS XR) and only answers it once that prompt can be confidently attributed to the target device — a jump host's own password prompt (single-hop ProxyJump) is never answered; that hop must still use non-interactive key/agent authentication. Key/agent authentication that succeeds without ever showing a password prompt is completely unaffected — no password is sent. For Telnet, only a bounded classic-IOS- style login sequence is automated (optional Username:, then Password:, then the device's own exec prompt) — never a generic prompt-answering loop, and never enable/TACACS/OTP/MFA automation. If authentication definitively fails or is rejected (either transport), terminal_open() fails with a sanitized error (never the credential itself) and, if it created a new session for this attempt, closes it; a pre-existing session is never destroyed just because a later open encounters an unusual state, and an already-authenticated session stays fully idempotent (no send, no disturbance). See docs/architecture.md for the full design.

Telnet itself remains unencrypted, transmitting the login and all session content in the clear — Network Lab MCP only keeps the credential private from the AI/MCP client, it does not (and cannot) make Telnet a secure transport. Telnet remains appropriate only for isolated lab environments.

Password display policy

Network Lab MCP is primarily a lab tool, so explicit local CLI configuration display — show running-config / show configuration / bare show for an access-info device or jump host — shows password in clear text, not masked:

network-lab(config-access-device-R1)# show running-config
access-info sample
 device R1
  type iosxr
  address 192.0.2.11
  transport ssh
  port 22
  username example-user
  password example-password
 !
!

This is the only place a password is ever shown in clear text. Every other boundary is unchanged and unweakened:

• MCP tool results (get_active_topology(), get_execution_instructions(), every terminal_*() return value) never include it.

• Logs, exceptions, and every %-prefixed error message never include it.

• ? help and Tab completion never reveal or offer it as a candidate.

• The CLI's in-memory command history never retains a password-setting command, even abbreviated.

Single-hop SSH jump hosts (ProxyJump)

access-info can declare reusable jump_hosts, each a generic endpoint (type: host — never a network-device type) reached over SSH:

name: sample

jump_hosts:
  jump1:
    type: host
    address: 192.0.2.10
    transport: ssh
    port: 22
    username: example-user
    password: example-password

devices:
  R1:
    type: iosxr
    address: 192.0.2.11
    transport: ssh
    port: 22
    username: example-user
    password: example-password
    jump_host: jump1

A device's optional jump_host field references one jump host by name within the same access-info definition. terminal_open() then launches native OpenSSH with -J (conceptually ssh -J example-user@192.0.2.10:22 -p 22 example-user@192.0.2.11) instead of connecting directly — no shell-hop automation, just OpenSSH's own ProxyJump tunneling one SSH connection through another. The tmux pane still only ever shows one interactive session to read/send against, exactly like a direct connection.

Constraints (all enforced by lab.validate_access_info_data(), so a manually edited, invalid committed file fails closed the same way a rejected CLI commit would): a jump host's type must resolve to exactly host; a jump host's transport, if set, must be ssh; a device's transport must also be ssh when it references a jump_host; and single-hop only — a jump host has no jump_host field of its own. See docs/cli_reference.md for the full command reference (jump-host <name> under access-info definition mode).

Dedicated tmux environment

All Network Lab MCP terminal sessions run on a dedicated tmux server, separate from any tmux environment you use interactively, so terminal_list()/terminal_close() are always safe from interfering with unrelated sessions. Production topology-device sessions (network-lab-device-<device-id>), Discovery's private bootstrap sessions (network-lab-discovery-<device-id>), and local validation-only sessions (network-lab-validation-<validation-id>) live in structurally distinct namespaces, distinguished only by a fixed prefix — never by pattern-matching on a device's name, so a topology device literally named validation-router maps to the ordinary production session network-lab-device-validation-router, not a validation session. Terminal sessions live in tmux independent of the MCP server process: the server keeps no session registry of its own, never destroys a session on exit, and a restarted server rediscovers and reuses any existing session instead of creating a duplicate.

stdio / stdout rule

The MCP server communicates over stdio, and stdout is reserved for MCP protocol traffic. It never uses print(), prints no startup banner, and sends all diagnostic logging to stderr.

Supported device types & Discovery scope

A device's optional type field, when present (in either topology or access-info), must be one of:

• iosxr — Cisco IOS XR

• iosxe — Cisco IOS XE

• ios — classic Cisco IOS (its own explicit type, never a compatibility label under iosxe — a device that actually runs classic IOS, not IOS XE, should be typed ios)

• nxos — Cisco NX-OS

• host — generic host / endpoint (e.g. a jump host, or a traffic generator)

lab.normalize_device_type() is the single validation primitive for this enum: an unambiguous abbreviation like type nx normalizes to nxos, and exact ios always wins over abbreviation resolution (never rejected merely because it is also a prefix of iosxr/iosxe).

Topology discovery

discover topology (global configuration mode only) reads the committed active_access_info and runs read-only neighbor discovery against its iosxr, iosxe, and ios devices — host is skipped (not an error); nxos is unsupported and skipped:

It never installs/activates a package, enables LLDP/CDP, or changes router configuration; it requires all selected targets to succeed for neighbor discovery (any login/command/timeout failure fails the whole operation before the prior candidate is touched), and it always ends in topology configuration mode with the result applied as a candidate — exactly like a manually typed topology <name>. It never commits and never changes active_topology itself; committing the result, and separately selecting it as the active topology, both remain explicit human steps. NX-OS discovery, SNMP/NETCONF/RESTCONF, multi-hop jump chains, and a generic discovery/plugin framework are all out of scope. See docs/architecture.md for the full pipeline, including multi-protocol link reconciliation and how an unresolved neighbor's evidence stays reviewable through the observing device's own terminal log.

L3 topology enrichment

Alongside neighbor discovery, each interface with a directly observed IPv4 address may also be enriched with that address plus its VRF:

devices:
  R1:
    type: iosxr
    interfaces:
      GigabitEthernet0/0/0/2:
        ipv4_address: 10.0.12.1
        vrf: default

This is deliberately narrow: no prefix length is ever inferred, no subnet/link inference from addresses is ever performed, and no operational state (up/down, holdtime, counters) is ever persisted into topology — ask the device directly for that. get_active_topology() returns this data with no schema change, since it already returns the whole validated topology mapping verbatim.

Real-lab acceptance tests are gated

Real-lab tests are never run by a plain pytest:

NETWORK_LAB_REAL_TESTS=1 pytest tests/test_real_lab_iosxr.py -v --tb=line

(--tb=line, and never --showlocals, so a real device's password never ends up in a failure traceback.)

Documentation

• docs/architecture.md — the full system architecture: design goals, configuration model, MCP interface, device access, terminal architecture, topology discovery, the CLI control plane, security boundaries, and persistence/lifecycle.

• docs/mcp_tools.md — the current seven-tool MCP contract.

• docs/cli_reference.md — the full human CLI command reference.

• docs/scenario_format.md — the current scenario/reference format.

Directory structure

network-lab-mcp/
├── pyproject.toml
├── README.md
├── .gitignore
├── run_cli.sh                 # human CLI launcher
│
├── src/
│   └── network_lab_mcp/
│       ├── __init__.py
│       ├── mcp_server.py      # stdio MCP server, defines the 7 tools
│       ├── lab.py             # running-config/topology/access-info/scenario/reference loading
│       ├── terminal.py        # tmux session management, ssh/telnet launch
│       ├── discovery.py       # topology discovery (LLDP/CDP + L3 enrichment)
│       │
│       └── cli/                       # human-facing CLI
│           ├── __init__.py
│           ├── main.py                # REPL, prompt rendering, key bindings, dispatch
│           ├── config.py              # candidate configuration, dirty state, commit/clear
│           ├── grammar.py             # command grammar single source of truth
│           └── editor.py              # external ($VISUAL/$EDITOR/vim) YAML editor support
│
├── lab/
│   ├── settings.example.yaml  # tracked template (running-config)
│   ├── settings.yaml          # local only, gitignored (running-config)
│   ├── principles.yaml
│   │
│   ├── access-info/
│   │   ├── sample.yaml        # tracked; fictional sample only
│   │   └── ...                # any other file here is local/private, gitignored
│   │
│   ├── topologies/
│   │   └── sample.yaml        # tracked; safe logical data, documentation-only addresses
│   │
│   ├── scenarios/
│   │   └── sample.yaml        # tracked; every other file here is local/private, gitignored
│   │
│   └── references/
│       └── sample.yaml        # tracked; every other file here is local/private, gitignored
│
└── docs/
    ├── architecture.md
    ├── mcp_tools.md
    ├── cli_reference.md
    └── scenario_format.md

lab/access-info/sample.yaml and lab/topologies/sample.yaml are independent sample files that happen to share a name purely by convention (both are the one canonical public sample for their respective concept) — running-config's explicit access-info <name> / topology <name> selections are the only real association between an access-info definition and a topology; filenames are never matched to infer one.

Sample lab

lab/topologies/sample.yaml, lab/access-info/sample.yaml, lab/scenarios/sample.yaml, and lab/references/sample.yaml are tracked in git and describe one small, coherent fictional lab (R1/R2, an optional jump1 jump host). The topology holds only safe logical data; the access-info definition holds the matching fictional connection data, using only documentation-only addresses from the RFC 5737 192.0.2.0/24 range. These addresses are not reachable and must not be used as real connectivity targets, and the sample password (example-password) is not a real credential — create your own private access-info for a real lab. The samples exist to validate YAML loading, MCP structured output, device-access resolution, and device-name/session-name mapping.

Git safety design

This repository is meant to be shared publicly, but real access-info YAML contains device names, management addresses, usernames, passwords, and other private lab information; real scenario/reference files may also describe private task or customer context. Rather than relying on documentation alone, .gitignore provides a default technical guard: only each concept's one fictional sample.yaml is tracked, and every other file under lab/topologies/, lab/access-info/, lab/scenarios/, and lab/references/ is gitignored by default, regardless of its name.

lab/settings.yaml
lab/topologies/*.yaml
!lab/topologies/sample.yaml
lab/access-info/*.yaml
!lab/access-info/sample.yaml
lab/scenarios/*.yaml
!lab/scenarios/sample.yaml
lab/references/*.yaml
!lab/references/sample.yaml

This is not a complete security boundary — it is a default that lowers the chance of accidentally committing real credentials or private lab data to a public repository. Treat any access-info file that leaves this repository as sensitive regardless of what git tracks. Topology YAML never carries private access fields at all (lab.validate_topology_data() rejects address/transport/port/username/password outright), so it is a much lower-risk file even before considering .gitignore.

Current limitations

• Topology discovery supports IOS XR (LLDP + CDP), IOS XE (LLDP + CDP), and classic IOS (CDP only): no NX-OS discovery, no SNMP/NETCONF/RESTCONF, and no generic discovery plugin framework.

• L3 topology enrichment deliberately stores only a directly observed IPv4 address + VRF per interface: no prefix length, no subnet/link inference from addresses, and no operational state is ever persisted into topology.

• No automatic stale-link pruning after Discovery.

• terminal_open() automates SSH password authentication and classic-IOS- style Telnet username/password login only; it does not automate a host-key confirmation prompt, and terminal_send()/terminal_read() themselves remain a simple, unattended capture/send with no login automation of their own beyond that one-time terminal_open() step.

• Non-editable/wheel installation is not supported.

• access-info has no external-editor support (structured CLI editing only), unlike topology/scenario/reference.

• Single-hop OpenSSH ProxyJump only: a jump host cannot itself reference another jump host, and only type: host / transport: ssh jump hosts are supported.

• The case-only topology-name collision safeguard (topology <name>) is the only such safeguard; there is no equivalent for device <name> or for access-info/jump-host/scenario/reference names (identifiers remain fully case-sensitive regardless).

• Scenario/reference schema is intentionally not fixed — only "valid YAML, root is a mapping" is enforced (see docs/scenario_format.md).

MCP SDK

Network Lab MCP uses the official MCP Python SDK, pinned as mcp>=2.2,<3 in pyproject.toml. It uses the SDK's MCPServer class over the stdio transport. See docs/mcp_tools.md for the tool reference.

Version, license

Run help in the CLI (./run_cli.sh) for a Quick Start covering the typical configuration workflow, and show version (EXEC mode only) for the exact version, release date, source revision, and license currently running. help claude explains how Claude Code uses Network Lab MCP.

Network Lab MCP is licensed under the GNU General Public License v3.0 (see LICENSE). Version, author, and license metadata are declared once in pyproject.toml and read at runtime via importlib.metadata — show version's output and this README are the same source, never two independently maintained copies.