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.

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.