cml-mcp-server
Integration with Cisco Modeling Labs (CML) for managing network labs, including creating/deleting labs, managing nodes and links, applying configurations, and deploying example network topologies.
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-server Deploy the two_router_ospf example topology and start it."
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 (Model Context Protocol) server for Cisco Modeling Labs (CML) v2.10.
It wraps Cisco's official virl2_client Python SDK to expose lab/topology
CRUD, node/link management, node configuration, and a catalog of ready-made
example network architectures as MCP tools - so an MCP client (Claude Code,
Claude Desktop, etc.) can build and run network labs for testing designs and
configs.
Setup
cd cml-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cp cml-config.example.toml cml-config.toml # then fill in host / username / password
chmod 600 cml-config.tomlCredentials: config file vs. env vars
Connection settings can come from either a TOML config file or environment variables; env vars win if both are present. The config file is the recommended approach since it keeps credentials out of shell history and process-list-visible env, and out of MCP client config JSON.
cml-config.toml (project root) - searched first - or
~/.config/cml-mcp-server/config.toml, or an explicit path via
CML_CONFIG_PATH:
[cml]
host = "cml.example.com"
username = "api-user"
password = "change-me"
# verify_ssl = falseEquivalent env vars: CML_HOST, CML_USERNAME, CML_PASSWORD,
CML_VERIFY_SSL. CML_VERIFY_SSL accepts true/false or a path to a CA
bundle; it defaults to false since most CML controllers run with a
self-signed certificate.
Related MCP server: Packet Tracer MCP
Running
source .venv/bin/activate
cml-mcp-serverThis starts the server on stdio, ready to be attached to an MCP client.
Claude Code / Claude Desktop config
{
"mcpServers": {
"cisco-cml": {
"command": "/absolute/path/to/cml-mcp-server/.venv/bin/cml-mcp-server"
}
}
}Or point at an explicit config file / use env vars instead:
{
"mcpServers": {
"cisco-cml": {
"command": "/absolute/path/to/cml-mcp-server/.venv/bin/cml-mcp-server",
"env": {
"CML_CONFIG_PATH": "/absolute/path/to/cml-config.toml"
}
}
}
}Tools
Labs
list_labs,get_lab_topologycreate_lab,delete_labstart_lab,stop_lab,wipe_lab
Platform catalog
list_node_definitions- available platform types (iosv, iosvl2, csr1000v, nxosv, asav, alpine, unmanaged_switch, ...), depends on which reference images are imported into your CML controller
Nodes
add_node,remove_nodestart_node,stop_nodeget_node_config,set_node_config(day-0 startup config)extract_node_config(pull the running config off a booted node)get_node_console_log
Links
add_link,remove_link- by default connects the next free interface on each node; interface labels can be given explicitly
Bulk topology building
build_topology- create a whole lab (nodes + links + configs) in one call from a node/link speclist_example_topologies,get_example_topology,deploy_example_topology- a small catalog of ready-made architectures:two_router_ospf- single-area OSPF adjacencybgp_two_as_peering- eBGP between two ASesthree_tier_campus- core/distribution/access skeletonleaf_spine_datacenter- 2-spine/2-leaf full-mesh underlayfirewall_dmz- IOS zone-based firewall with inside/outside/DMZ zones
These templates default to
iosv/iosvl2(bundled with every CML install); swapnode_definitionper node for platform-specific images (e.g.nxosv,csr1000v,asav) if you have them.
Typical flow
list_node_definitions()- see what platforms are available.Either:
list_example_topologies()→deploy_example_topology("two_router_ospf"), ordescribe an architecture and let the assistant design a node/link spec, then call
build_topology(...)directly.
start_lab(lab_id), thenget_lab_topology(lab_id)to check node state.get_node_console_log/extract_node_configto inspect a running node;set_node_config+wipe_lab+start_labto iterate on day-0 config.delete_lab(lab_id)when done - this is permanent.
Security notes
This server can create, start, and delete labs and nodes on the target CML controller. Scope the CML account to a dedicated user if you don't want it operating with full admin rights, and treat
delete_lab,wipe_lab, andremove_nodeas destructive, unrecoverable actions.Credentials are only ever read (from
cml-config.tomlor env vars); nothing is written to disk by this server. Keep the config file out of version control (it's in.gitignoreby default) and permissioned600.Session/token handling (login, refresh, re-auth) is delegated entirely to
virl2_client.
Available Tools
22 toolsadd_linkA
Connect two nodes with a link. If iface_a/iface_b (interface labels, e.g. 'GigabitEthernet0/1') are omitted, the next free interface on each node is used, creating one if needed.
Inputs: lab_id (required), node_a_id (required), node_b_id (required), iface_a, +1 more. Returns: object
add_nodeA
Add a node to an existing lab.
node_definition: a platform id from list_node_definitions(), e.g. 'iosv', 'iosvl2', 'alpine', 'unmanaged_switch'. configuration: day-0 startup config text (e.g. a full IOS config), applied on first boot.
Inputs: label (required), lab_id (required), node_definition (required), x, +5 more. Returns: object
build_topologyA
Create a whole lab - nodes, links, and configs - in one call. Use this when you already have a topology design in mind (e.g. from list_example_topologies, or one you designed yourself from the user's description) rather than calling create_lab/add_node/add_link repeatedly.
nodes: [{id, label, node_definition, x?, y?, image_definition?,
configuration?, cpus?, ram?}, ...]
id is a caller-chosen local key used only to wire up links below;
it is not sent to CML.
links: [{node_a, node_b, iface_a?, iface_b?}, ...]
node_a/node_b reference the local ids from nodes. iface_a/iface_b
are optional interface labels (e.g. 'GigabitEthernet0/0'); if omitted
the next free interface on each node is used.
start: if True, start the lab immediately after building it.
Returns the new lab's id plus a map from each local node id to its real CML node id, so you can immediately call add_node/add_link/set_node_config etc. against the result.
Inputs: links (required), nodes (required), lab_title (required), start, +1 more. Returns: object
create_labB
Create a new, empty lab. Use add_node/add_link or build_topology to populate it.
Inputs: title (required), description. Returns: object
delete_labC
Permanently delete a lab and everything in it. This cannot be undone.
Inputs: lab_id (required). Returns: object
deploy_example_topologyA
Build one of the built-in example topologies (see list_example_topologies) as a new lab, unmodified. For customization, use get_example_topology + build_topology instead.
Inputs: name (required), start, lab_title. Returns: object
extract_node_configA
Pull the current running configuration off a booted, converged node and return it. Requires the node to be started.
Inputs: lab_id (required), node_id (required). Returns: result
get_example_topologyA
Get the full node/link spec for a named example topology (from list_example_topologies), so it can be inspected or edited before building - e.g. to change addressing, swap node_definitions for platform-specific images, or add nodes - then passed to build_topology.
Inputs: name (required). Returns: object
get_lab_topologyA
Get full topology detail for a lab: its nodes, links, and their state.
Inputs: lab_id (required). Returns: object
get_node_configA
Get the stored day-0 startup configuration text for a node.
Inputs: lab_id (required), node_id (required). Returns: result
get_node_console_logB
Get console output captured for a node (console_id 0 is the main
console on most platforms). Optionally limit to the last lines lines.
Inputs: lab_id (required), node_id (required), lines, console_id. Returns: object
list_example_topologiesA
List built-in example network architectures (e.g. OSPF/BGP routing labs, a three-tier campus, a leaf-spine data center fabric, a zone-based firewall with a DMZ) that can be deployed directly with deploy_example_topology, or fetched with get_example_topology and customized before calling build_topology.
Inputs: no named parameters. Returns: result
list_labsA
List CML labs. By default only labs owned by the authenticated user; set show_all=True for every lab on the controller (needs admin rights).
Inputs: show_all. Returns: result
list_node_definitionsA
List platform/node types available on this controller (e.g. iosv,
iosvl2, csr1000v, nxosv, asav, alpine, unmanaged_switch, external_connector).
Use the returned 'id' as node_definition when adding nodes. Availability
depends on which reference platform images have been imported into CML.
Inputs: no named parameters. Returns: result
remove_linkC
Remove a link between two nodes.
Inputs: lab_id (required), link_id (required). Returns: object
remove_nodeA
Remove a node, and any links/interfaces attached to it, from a lab.
Inputs: lab_id (required), node_id (required). Returns: object
set_node_configA
Set a node's day-0 startup configuration text. Takes effect the next time the node is (wiped and) started. To capture a running node's current config instead, use extract_node_config.
Inputs: lab_id (required), node_id (required), configuration (required). Returns: object
start_labB
Start (boot) every node in a lab.
Inputs: lab_id (required), wait. Returns: object
start_nodeC
Start (boot) a single node.
Inputs: lab_id (required), node_id (required), wait. Returns: object
stop_labC
Stop every node in a lab.
Inputs: lab_id (required), wait. Returns: object
stop_nodeC
Stop a single node.
Inputs: lab_id (required), node_id (required), wait. Returns: object
wipe_labA
Wipe every node's disks back to initial state. Startup (day-0) configuration set via set_node_config is preserved; runtime/learned state is discarded. The lab must be stopped first.
Inputs: lab_id (required), wait. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Each tool targets a distinct resource and action, from lab-level operations (create_lab, start_lab) to node-level (add_node, stop_node) and link-level (add_link, remove_link). Aggregates like build_topology and example-specific tools are clearly separated, and even similar-looking config tools (get_node_config vs extract_node_config) are explicitly differentiated.
All tools follow a consistent verb_noun pattern in snake_case (e.g., list_labs, create_lab, add_node, delete_lab). Verbs and nouns are predictable, and related actions use clear prefixes like start_/stop_, add_/remove_, and get_/list_.
With 22 tools, the server sits in the heavy range (16-25) according to the calibration rubric. While each tool serves a clear purpose, the sheer number might be overwhelming for an agent, and some operations (e.g., example topology deployment) could have been consolidated without losing clarity.
The tool surface covers core lab lifecycle (create, delete, start, stop, wipe), node management (add, remove, config, console), and link management (add, remove). However, there is no direct update for lab metadata or node resources (RAM, image), and no way to edit a link without recreating it, which are minor gaps agents can work around.
Maintenance
Related MCP Connectors
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
MCP Server for Orderly Network - Documentation and SDK patterns
MCP server for innovationlab documentation, generated by doc2mcp.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA comprehensive toolkit that enables automated interaction with Cisco Modeling Labs (CML) for creating network topologies, configuring devices, and managing lab environments.2-
- AlicenseNot gradedqualityAmaintenanceAn MCP server that allows LLMs to create, configure, validate, and explain Cisco Packet Tracer network topologies. It provides a comprehensive suite of tools for generating deployment scripts, CLI configurations, and automated network troubleshooting.1,494 PyPI377MIT
- AlicenseAqualityDmaintenanceThin MCP server for Cisco CML2 that exposes the live OpenAPI specification and a generic API call tool, enabling models to interact with CML2 by reading the spec first.2MIT
- AlicenseBqualityDmaintenanceAn MCP server that gives Claude and other LLM agents programmatic access to EVE-NG network labs, enabling creation, configuration, and management of virtual network topologies through natural language.142Apache 2.0