F
licenseNot graded
qualityD
maintenanceA comprehensive toolkit that enables automated interaction with Cisco Modeling Labs (CML) for creating network topologies, configuring devices, and managing lab environments.
1
-
cml-mcp-server
by dr-stutters
Provides integration with Cisco Modeling Labs (CML 2.x), enabling exploration, creation, operation, and troubleshooting of virtual network labs. Supports managing labs, nodes, links, configurations, packet captures, reachability checks, recipes, and topology exports.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cml-mcp-serverbuild a lab with two IOS routers connected and test reachability"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
cml-mcp-server
An MCP server for Cisco Modeling Labs (CML 2.x): explore, build, run and troubleshoot network labs from an AI assistant. It's built on stutters-mcp-core and tested against CML 2.10.
Disclaimer. This is not an official Cisco product or repository, and it isn't supported or endorsed by Cisco. It's a personal project by @dr-stutters, for lab and learning use only: don't point it at production systems. It's provided as is, with no warranty (see the license). Cisco and Cisco Modeling Labs are trademarks of Cisco Systems, Inc.
82 tools in three tiers: 42 read, 32 write, 8 dangerous (incl.
cml_api_callfor non-GET), and the promptcml_build_test_lab. Write and dangerous tools (and the prompt) are off by default.Names or ids everywhere. Labs take a title or a UUID, nodes take a label, and links take
r1<->r2orr1:Ethernet0/0<->r2:Ethernet0/0.Preview-first writes. A write call without
confirmchanges nothing. It returns a preview (diffs, chosen interfaces, blockers CML would reject) and a single-use confirm token. Every preview has aback-out:line and every applied result anundo(the reversing call and its arguments, e.g.cml_delete_nodewith the new node's id, or why there is none: wipes and deletes say archive first); the audit log records it too.Task tools.
cml_build_labbuilds a whole lab from a compact spec (day-0 configs, extra config files, console logins, external connectors),cml_wait_for_convergedreports boot progress (and can wait for a console message),cml_check_reachabilityproves what a lab can ping, andcml_diff_labcompares a lab with another lab or a saved export.Real platforms on the console. IOS/IOS-XE, NX-OS (POAP skipped), FTD CLISH (no
enable,mode='exec'forconfigure manager add ...), Linux. Questions ([confirm],[yes/no]) are answered on request, runaway commands get Ctrl-C.Lab recipes for the other suite servers. FTDv for FMC, an unregistered FTDv HA pair, IOS-XE routers for Catalyst Center, a Cat9kv 802.1X switch (IBNS 2.0) with MAB and EAP-TLS clients for ISE, an AD-user 802.1X client behind an FMC-managed FTD for user-based firewalling:
cml_list_recipes,cml_build_recipe,cml_verify_recipe(pass/fail contract, incl. ISE live sessions),cml_run_recipe_action(e.g. switch the logged-in user) and the promptcml_build_test_lab;cml_plan_licencessays which labs to stop. Recipes not yet released (a PR's checkout) load fromCML_RECIPE_DIRS. See src/cml_mcp/recipes/README.md.Test oracles.
cml_diff_node_configshows what another server changed on a device;cml_capture/cml_summarize_capturedecode RADIUS, EAPOL, OSPF, DHCP, the SGT in VXLAN-GPO and CMD frames, LISP, BGP, BFD, IKEv2/ESP, NetFlow/IPFIX, syslog and DNS from a link capture.Degraded networks and diagrams.
cml_apply_link_scenarioputs named impairments on a link (wan-good, wan-satellite, lossy-wifi, brownout, or a timedflap);cml_export_topologydraws a lab as Mermaid or draw.io with addresses, andcml_annotate_labmakes a lab self-describing.Spec escape hatch.
cml_search_specandcml_get_definitionread the controller's own OpenAPI document.cml_api_callreaches any endpoint: GET in the read tier, other methods in the dangerous tier.
Quickstart (5 minutes)
You need: a CML account for the server, a regular (non-admin) user is enough (read-only to start: labs shared
with it as lab_view + lab_exec and a resource pool with 0 node licences, see
docs/least-privilege.md). Never the built-in admin.
A. On your laptop (stdio), from a release wheel. Every GitHub release has a wheel with stutters-mcp-core bundled in; it needs only PyPI dependencies.
WHEEL=https://github.com/dr-stutters/cml-mcp-server/releases/download/v0.18.0/cml_mcp_server-0.18.0-py3-none-any.whl
export CML_URL=https://cml.example.com CML_USERNAME=mcp-cml-viewer CML_PASSWORD='...'
uvx --from "$WHEEL" cml-mcp-server check # preflight: reachability, TLS, login, version, admin flag
claude mcp add cml -e CML_URL=$CML_URL -e CML_USERNAME=$CML_USERNAME -e CML_PASSWORD="$CML_PASSWORD" \
-- uvx --from "$WHEEL" cml-mcp-server # stdio is the default transportClaude Desktop (claude_desktop_config.json), same idea:
{
"mcpServers": {
"cml": {
"command": "uvx",
"args": ["--from", "https://github.com/dr-stutters/cml-mcp-server/releases/download/v0.18.0/cml_mcp_server-0.18.0-py3-none-any.whl", "cml-mcp-server"],
"env": {"CML_URL": "https://cml.example.com", "CML_USERNAME": "mcp-cml-viewer", "CML_PASSWORD": "..."}
}
}
}B. On a shared host (HTTP), from the image. Multi-arch (amd64/arm64), signed, with an SBOM:
ghcr.io/dr-stutters/cml-mcp-server:<version> (or :latest).
docker run --rm -e CML_URL=https://cml.example.com -e CML_USERNAME=mcp-cml-viewer -e CML_PASSWORD='...' \
ghcr.io/dr-stutters/cml-mcp-server cml-mcp-server check
docker run --rm ghcr.io/dr-stutters/cml-mcp-server cml-mcp-server token alice # one token per person
cp .env.example .env && chmod 600 .env # CML_*, MCP_AUTH_TOKENS=alice:sha256:...
docker compose up -d # pulls the image; http://localhost:8032/mcpFor a team, use docs/deploying.md: read-only by default, per-user tokens in the audit log, several controllers, the shared node-licence budget, TLS with Caddy, upgrades.
check runs without an MCP client and exits 1 on a failure (--json for scripts, --strict to fail on
warnings, --instance training for one controller). It reports reachability and TLS trust of the controller
API, the login, the CML version against the tested matrix (2.10; 2.7 minimum), the API user's admin flag
against the enabled tiers (an admin behind a read-only server warns; a regular user with the dangerous tier on
warns that admin-only tools will fail) and, with writes on, the node licences the account may start (its
resource pool, else the controller licence):
OK config https://cml.example.com; tiers enabled: read, write
OK reachability[api] CML API answered; logged in as mcp-cml-operator (41 ms)
OK tls certificate verified against the system trust store
OK auth credentials accepted
OK role role 'mcp-cml-operator (regular user)' allows the enabled tier(s): read, write
OK version Cisco Modeling Labs 2.10.0+build.13: tested
WARN licences resource pool 'mcp-cml-operator-pool' leaves 0 node licences free (12 of 12 in use): ...
-> Raise the pool's licences (Tools > Resource Pools; ...) or stop labs (cml_plan_licences says which).cml-mcp-server serve --http serves HTTP (needs MCP_AUTH_TOKENS); cml-mcp-server config shows the
effective settings and where each came from, without contacting CML.
From source
git clone https://github.com/dr-stutters/cml-mcp-server && cd cml-mcp-server
python3 scripts/bundle_core.py vendor # bundles the pinned stutters-mcp-core as cml_mcp._core (needs git)
cp .env.example .env && chmod 600 .env # set CML_URL, CML_USERNAME, CML_PASSWORD
uv sync
uv run cml-mcp-server checkThe shared stutters-mcp-core library (with its tasks extra) is
bundled into the package as cml_mcp._core (core ADR-005): the wheel, the sdist and the Docker image need
nothing but their PyPI dependencies, with no git dependency and no token. uv build writes the wheel to dist/.
The pinned core tag is [tool.bundle-core] in pyproject.toml and cml_status reports it as core_version.
The vendored copy is generated, not committed: scripts/bundle_core.py vendor writes it, check reports drift,
and update --tag vX.Y.Z moves the pin (then uv lock). A plain git checkout has no cml_mcp/_core, so install
from a release wheel rather than git+https://....
Claude Code: stdio (local)
claude mcp add cml -- uv --directory /path/to/cml-mcp-server run cml-mcp-server
# to allow changes:
claude mcp add cml -e MCP_ENABLE_WRITES=true -- uv --directory /path/to/cml-mcp-server run cml-mcp-serverClaude Code: HTTP (shared container)
uv run cml-mcp-server token alice # prints a bearer token + the MCP_AUTH_TOKENS entry
claude mcp add --transport http cml http://cortex:8032/mcp --header "Authorization: Bearer <token>"or in .mcp.json:
{
"mcpServers": {
"cml": {
"type": "http",
"url": "http://cortex:8032/mcp",
"headers": { "Authorization": "Bearer ${CML_MCP_TOKEN}" }
}
}
}Related MCP server: gns3-mcp
Tools
Read (always on)
Tool | What it does |
| Version, API user, compute/controller health problems, licence summary, server config |
| Controller and compute health flags, with a problem list |
| CPU, RAM and disk per compute host; running nodes and allocated resources; licence capacity |
| Smart Licensing registration and authorization, features, expiry |
| Labs with state and counts; one lab with convergence, node states and resources in use |
| Compact wiring summary (node interface -> peer, links, conditioning); |
| Topology YAML, valid and re-importable when masked (pyATS passwords |
| Change and state history, newest first, with the fields that changed |
| The pyATS testbed CML generates (passwords masked) |
| Nodes with state, image and resources (optionally live CPU/RAM); one node with interfaces, peers and config |
| Recent serial console output, escape codes stripped, optional |
| Run show, ping and traceroute (or |
| Per node, is the serial console usable: |
| Interfaces with MAC, state and peer; filter free or connected |
| IPs per interface: snooped by CML on external segments, or read from every node's CLI ( |
| Ping targets from nodes (per-OS syntax, VRF, FTD management) and return a pass/fail matrix with average RTT |
| Pre/post change snapshot of a lab (core snapshot contract): node and link states, link conditioning, IPv4 per interface, masked running-config hash per node, OSPF/BGP/EIGRP neighbours, and a ping matrix ( |
| Compare a |
| Networks an |
| Sample labs on the controller (filter by text or node type) |
| Links as |
| Decoded packets from a link capture (filter by protocol or text) |
| What can be built: interfaces, resources, boot markers, default configs |
| Installed images |
| Disk images in |
| Wait until a lab or node has booted, with progress notifications; |
| Diff a lab with another lab or a saved YAML: nodes, interfaces, links, config diff ( |
| Running config (from the console) vs day-0, startup, another node or a baseline; secrets masked |
| Decoded summary of a link capture: protocol mix, conversations, RADIUS/EAPOL/OSPF/DHCP/ARP/ICMP highlights; SGTs (VXLAN-GPO, CMD), LISP, BGP, BFD, IKEv2/ESP, NetFlow/IPFIX exporters, syslog, DNS; |
| Licences in use per lab, what a lab or recipe needs, which labs to stop |
| Map a real site's devices (Catalyst Center / ISE / FMC inventories) to CML node definitions within a node/RAM budget: ready |
| Test-lab recipes, packaged and from |
| Named link scenarios with netem values and expected round-trip ping deltas; with a lab, its conditioned links and flap jobs |
| Mermaid, draw.io or JSON diagram of a lab with interface addresses (day-0 config, snooped or CLI) |
| A lab's drawn annotations (text, shapes), marking the ones this server wrote |
| OpenAPI search, operation and schema details, raw GET |
Write (MCP_ENABLE_WRITES=true, all preview-first)
Tool | What it does |
| Build a lab from |
| Create a lab from a sample lab |
| Create an empty lab, or create one from topology YAML (node definitions are checked; |
| Start (waits for convergence) or stop a lab; with node staging on, the start preview shows the staged |
| Stop several labs (a list, or every running lab except |
| Add a node; change its label, tags, position, boot |
| Boot behaviour of a lab: node staging ( |
| Replace a node's day-0 config and/or other day-0 files by name ( |
| Start or stop one node |
| Save running configs into the stored node configs (nodes whose definition has no config extraction, e.g. alpine, are listed under |
| Push config lines to a running device over its console ( |
| Push the same config lines to up to 20 running devices in one preview: templates with |
| Link two nodes (first free interfaces, never an FTDv/ASAv |
| Add latency, jitter, loss, bandwidth limits, duplication or corruption to a link, or clear it |
| Take a link down or bring it up (cable pull) |
| Take one interface down or up on a running node: only that end loses carrier, the peer stays up (FTD HA monitored interface, SD-WAN dead-WAN tests) |
| Pin an interface MAC (52:54:00:xx:xx:xx) or clear the pin ( |
| Packet capture on a link |
| Capture for N seconds and return the decoded summary in one call |
| Write a link's capture to a pcap file under |
| Archive a lab before deleting or wiping it: extracts the running configs of booted nodes whose definition supports it ( |
| Capture the simulated 802.11 medium at a wireless-ap / wireless-client node and decode it (SSIDs, auth/assoc, deauth reasons, EAPOL 4-way handshake, EAP identity/method) |
| Build a test-lab recipe, packaged or from |
| Run one of a recipe's actions on its lab, e.g. |
| Apply a named scenario to a link: wan-good, wan-satellite, lossy-wifi, brownout, or |
| Stop flap jobs and remove conditioning from a lab's links |
| Add notes, per-node address labels and the recipe's purpose/credential references as text annotations (re-runnable) |
| Make an uploaded disk image usable by a node definition (admin) |
Prompts (write tier): cml_replicate_site(site, fidelity, max_nodes) - Catalyst Center site (+ FMC firewalls, ISE NADs)
-> cml_plan_replica -> licence check -> cml_build_lab -> report gaps. cml_build_test_lab(recipe, reuse) - recipe -> licence plan -> build/start ->
converge -> verify -> hand-off block for the FMC / Catalyst Center / ISE server.
Dangerous (MCP_ENABLE_DANGEROUS=true as well)
Tool | What it does |
| Erase node disks ( |
| Delete ( |
| Stream a disk image from |
| Delete an image definition (refused while nodes use it) and/or a drop-folder file (admin) |
| Raw POST, PUT, PATCH or DELETE, preview-first |
Device CLI uses the controller's console server: SSH to the controller with the CML credentials,
then open /<lab>/<node>/0. This is the same path pyATS testbeds use. Device logins come from the
lab's pyATS testbed (node pyATS credentials, or the definition defaults).
CML only accepts config, RAM/CPU and new-interface changes while a node is wiped
(DEFINED_ON_CORE). It only deletes wiped nodes and labs. The previews say so and point to the
tool that fixes it.
Lab files and specs with secrets. A topology YAML for cml_import_lab can carry ${LAB_*} references
instead of passwords and keys, e.g. a CML Cookbook file rendered with
cookbook render <recipe> --input admin_password='${LAB_FTD_ADMIN_PASSWORD}'. The server fills them in from the
same LAB_* variables or CML_LAB_SECRETS_FILE as recipes, only inside nodes (day-0 configs, pyATS logins) and
only in the YAML it sends to CML. The tool call, the preview, the confirm token, the result and the audit log
carry only the placeholders, and lab notes and annotations keep them as written. The preview's lab_secrets
lists which secret goes into which node. A variable the server doesn't have blocks the import, and the blocker
names it. The filled topology is re-serialised, so YAML quoting is handled, but a value lands in a config's text
as it is: keep " and \ out of values used inside JSON day-0 configs. Unlike a recipe, the YAML comes from
the caller, and a node's day-0 config can do anything with the value it gets, so check lab_secrets before
you confirm. YAML without placeholders in its nodes is sent unchanged.
Restoring a masked export. cml_export_lab masks pyATS passwords as '********' and replaces a
password: / plain_text_passwd: line in a node file (cloud-init user-data) with ${LAB_NODE_PASSWORD}. Set
LAB_NODE_PASSWORD on the server (or in CML_LAB_SECRETS_FILE) and cml_import_lab fills it into those nodes;
without it the import is blocked by name. Set the pyATS logins again after a restore (or export with
include_credentials). A lab bigger than one response comes back in pages: call again with
offset=next_offset until complete, join the yaml of every page in order, and check sha256.
cml_build_lab does the same for a node's config, files and credentials, e.g.
"config": "username admin privilege 15 secret ${LAB_CLI_PASSWORD}" with
"credentials": {"username": "admin", "password": "${LAB_CLI_PASSWORD}"}: the preview's lab_secrets names
the nodes per secret, a missing variable blocks the build by name, CML's warnings and errors come back with the
reference, and the lab description, labels and tags stay as written.
Configuration
Variable | Default | Meaning |
| (required) | Controller URL, e.g. |
| API user (JWT login via | |
| A pre-issued JWT instead of username/password | |
| More controllers, each with | |
|
|
|
| CA file to verify the controller certificate | |
|
| Per-request timeout (s) and retries for idempotent calls |
| none / | Client-side throttling |
|
| Default wait for start/stop/convergence (s) |
| detected | Running licensed-node cap. Detected from |
|
| SSH port of the CML console server (used for device CLI) |
|
| Seconds a console call waits for another call on the same node before reporting it busy |
| dotenv file with the | |
| More recipe directories (comma- or | |
| The only directory | |
| The only directory | |
| The only directory | |
| Safety rails (docs/safety.md): labs no change may touch; labs the dangerous tools may wipe/delete (title globs or ids) | |
|
|
|
|
|
|
| known_hosts file for the console server's host key. When unset, the key is checked against | |
|
|
|
|
| HTTP listener |
|
| |
|
| Register the write and dangerous tiers |
|
| Run the long tools (image upload, builds/starts with wait, convergence waits, recipe verify, captures) as MCP background tasks for clients that support them; others still call them synchronously |
|
| Confirm-token lifetime (s) |
|
| OpenAPI index cache ( |
|
| Response size budget |
|
| Audit trail of previews and applied writes |
Least-privilege account
Run the server as a regular (non-admin) CML user, never admin. Tested on CML 2.10 with two accounts, both
created by scripts/seed_lab.py --least-privilege. Full guide: docs/least-privilege.md.
Read tier:
mcp-cml-viewer, labs shared with its group aslab_view+lab_exec(consoles needlab_exec), and a resource pool with 0 node licences. Every read tool works exceptcml_get_licensing(admin-only in CML).Write tier:
mcp-cml-operatorowns the labs it builds; its resource pool caps licences, CPU and RAM, and the start previews respect the pool.As a non-admin, licence planning counts only the labs the account can see (
scopesays so), and consoles of shared labs work.
Docker (HTTP)
docker compose up -d # pulls ghcr.io/dr-stutters/cml-mcp-server (MCP_IMAGE_TAG, default latest)
docker compose up -d --build # or build from this checkout (no token: core is bundled)
curl -s http://localhost:8032/health # {"status":"ok"}The container runs as non-root on a read-only root filesystem with all capabilities dropped. The spec cache lives in a named volume. Shared hosts (TLS, several controllers, per-user tokens, the shared licence budget, upgrades): docs/deploying.md.
Development
uv run ruff check && uv run ruff format --check && uv run mypy && uv run pytest
uv run pytest tests/live -m live # against the lab in .env; creates and deletes mcp-test-* labs
uv run python scripts/capture_fixtures.py mcp-test-probe # refresh redacted fixturesscripts/seed_lab.py [--start] [--recreate] creates a reusable lab, mcp-test-seed. It has two
IOL-XE routers running OSPF, an IOL-L2 switch and two Alpine hosts (h1 10.0.10.10 and h2
10.0.20.10, which can ping each other). Device logins are cisco/cisco.
Note: CML caps running licensed nodes across all labs (an unregistered controller in evaluation
mode allows 5; the test controller is now Enterprise with 20 + 50 expansion = 70). Unmanaged
switches and external connectors don't count. cml_plan_licences shows the cap and which labs to stop.
Live tests
Live tests build throwaway labs named mcp-test-* from fast-booting IOL nodes, run every tool,
and always delete what they created. They read the controller from .env (CML_URL plus a login) and skip
without one. Optional inputs (commented in .env.example); the tests that need them skip when they are unset:
Variable | Example | Used by |
|
|
|
|
|
|
|
|
|
|
|
|
-m live_recipes verifies only recipe labs that are already running on the controller.
Licence
MIT
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessResponsive
Related MCP Connectors
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Discover, run, inspect, build, test, and privately reuse AI workflows.
AI-callable tools for API mocking, testing, monitoring, security, and automation.
Discover, compare, route, and execute machine-accessible capabilities for AI agents.
Related MCP Servers
- AlicenseCqualityCmaintenanceEnables AI agents to control GNS3 network emulation labs. Supports building topologies, managing devices, capturing packets, and automating device CLIs.1001MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to interact with Cisco Modeling Labs (CML) using natural language, allowing creation, management, and automation of network labs.287 PyPI77BSD 2-Clause "Simplified"
- AlicenseNot gradedqualityBmaintenanceEnables LLMs to turn natural-language prompts into validated, deployed Cisco network topologies, including routing, switching, DHCP, VLANs, security auditing, and live device inspection.MIT