Skip to main content
Glama

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.toml

Credentials: 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 = false

Equivalent 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-server

This 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_topology

  • create_lab, delete_lab

  • start_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_node

  • start_node, stop_node

  • get_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 spec

  • list_example_topologies, get_example_topology, deploy_example_topology - a small catalog of ready-made architectures:

    • two_router_ospf - single-area OSPF adjacency

    • bgp_two_as_peering - eBGP between two ASes

    • three_tier_campus - core/distribution/access skeleton

    • leaf_spine_datacenter - 2-spine/2-leaf full-mesh underlay

    • firewall_dmz - IOS zone-based firewall with inside/outside/DMZ zones

    These templates default to iosv/iosvl2 (bundled with every CML install); swap node_definition per node for platform-specific images (e.g. nxosv, csr1000v, asav) if you have them.

Typical flow

  1. list_node_definitions() - see what platforms are available.

  2. Either:

    • list_example_topologies() → deploy_example_topology("two_router_ospf"), or

    • describe an architecture and let the assistant design a node/link spec, then call build_topology(...) directly.

  3. start_lab(lab_id), then get_lab_topology(lab_id) to check node state.

  4. get_node_console_log / extract_node_config to inspect a running node; set_node_config + wipe_lab + start_lab to iterate on day-0 config.

  5. 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, and remove_node as destructive, unrecoverable actions.

  • Credentials are only ever read (from cml-config.toml or env vars); nothing is written to disk by this server. Keep the config file out of version control (it's in .gitignore by default) and permissioned 600.

  • Session/token handling (login, refresh, re-auth) is delegated entirely to virl2_client.

Available Tools

22 tools
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_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

    A3.5/5.0

    Scored across 22 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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_.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers