An MCP server that provides access to common Cisco Modeling Labs (CML) operations.
Model Context Protocol (MCP) Server for Cisco Modeling Labs (CML)
This MCP server provides access to common Cisco Modeling Labs (CML) operations. It is published as io.github.xorrkaz/cml-mcp and is associated with topics including cml, mcp-server, and cisco-modeling-labs.
🛠️ Key Features
Exposes operations for Cisco Modeling Labs (CML)
Intended to allow interaction with CML operations
🚀 Use Cases
Using an MCP client to work with a CML-based network lab
Accessing “common CML operations” via MCP
⚡ Developer Benefits
Integrates CML lab interactions into an MCP workflow
Server identity includes mcp-name: io.github.xorrkaz/cml-mcp
⚠️ Limitations
Provided description is truncated and does not specify supported tools, detailed capabilities, or tool count
Model Context Protocol (MCP) Server for Cisco Modeling Labs (CML)
mcp-name: io.github.xorrkaz/cml-mcp
Overview
cml-mcp brings the power of AI assistants to your network lab! This tool allows you to interact with Cisco Modeling Labs (CML) using natural language through AI applications like Claude Desktop, Claude Code, and Cursor.
Instead of clicking through menus or writing scripts, simply tell the AI what you want to do in plain English—like "Create a new lab with two routers and configure OSPF" or "Show me the running config on Router1"—and watch it happen automatically.
This is accomplished through the Model Context Protocol (MCP), a standard way for AI applications to interact with external tools and services. Think of it as giving your AI assistant a direct connection to your CML server.
Features
Create Lab Topologies: Tools to create new labs and define network topologies from scratch or using full topology definitions.
Query Status: Tools to retrieve detailed status information for labs, nodes, links, annotations, and the CML server itself.
Control Labs and Nodes: Tools to start, stop, and wipe labs or individual nodes as needed.
Manage CML Users and Groups: Tools to list, create, and delete local users and groups (requires admin privileges).
Visual Annotations: Add visual elements (text, rectangles, ellipses, lines) to lab topologies for documentation and organization.
Link Management: Connect nodes, configure link conditioning (bandwidth, latency, jitter, loss), and control link states.
Packet Capture: Start, stop, and retrieve packet captures (PCAP) from network links for traffic analysis with Wireshark or other tools.
Node Configuration: Configure node startup configurations and send CLI commands to running devices.
Run Commands on Devices: Using PyATS, MCP clients can execute commands on virtual devices within CML labs.
Console Log Access: Retrieve console logs from running nodes for troubleshooting and monitoring, with support for selecting specific serial console ports.
Modular Architecture: Tools are organized into logical modules (labs, nodes, links, pcap, etc.) for maintainability and extensibility.
Access Control Lists (HTTP Mode): When running in HTTP transport mode, you can restrict which users can access which tools using a YAML-based ACL configuration file.
Observability: Optional OpenTelemetry tracing exports spans for every tool call to any OTLP-compatible backend (Jaeger, Grafana Tempo, Datadog, etc.).
Quick Start
Installation
The easiest way to get started is using uvx with Claude Desktop (or other MCP-compatible clients). The uvx tool automatically downloads and runs the server without manual installation steps.
Configuration: Find and edit your Claude Desktop configuration file (claude_desktop_config.json). Add the following:
Important: Replace the placeholder values with your actual CML server details:
CML_URL: Your CML server address (e.g., https://cml.example.com or https://10.10.20.50)
CML_USERNAME and CML_PASSWORD: Your CML login credentials
CML_VERIFY_SSL: TLS certificate verification now defaults to "true". CML ships with a self-signed certificate out of the box, so most users need to set this to "false". Leave it at "true" only if you have installed a CA-signed certificate on your CML server (or point CA_BUNDLE at a file containing your self-signed certificate).
TIP
"Command not found" for uvx? MCP clients like Claude Desktop run in a restricted environment that does not always inherit your shell's PATH. If uvx can't be found, use its full path in the "command" field. To find it, run which uvx in a terminal on macOS/Linux, or where uvx in Command Prompt on Windows (e.g., "/Users/alice/.local/bin/uvx" on macOS, "C:\Users\alice\.local\bin\uvx.exe" on Windows). The same applies to uv, npx, or any other command used in MCP configurations.
Need more capabilities?
For device CLI command execution, use cml-mcp[pyats] instead of cml-mcp in the args
For Docker, Windows (WSL), or HTTP server mode, see INSTALLATION.md
wipe_cml_lab - Wipe all node data/configurations (prompts for confirmation if client supports it)
delete_cml_lab - Delete a lab (prompts for confirmation if client supports it)
get_cml_lab_by_title - Find a lab by its title
download_lab_topology - Download lab topology as YAML file
clone_cml_lab - Clone a lab with optional new title
Node Management
get_cml_node_definitions - List available node types
get_node_definition_detail - Get detailed info about a specific node type
add_node_to_cml_lab - Add a node to a lab
get_nodes_for_cml_lab - Get all nodes in a lab with operational data
configure_cml_node - Set node startup configuration
start_cml_node - Start a specific node
stop_cml_node - Stop a specific node
wipe_cml_node - Wipe node data (prompts for confirmation if client supports it)
delete_cml_node - Delete a node (prompts for confirmation if client supports it)
get_console_log - Get console output history for a node; optional console index selects the serial port (default 0; Docker-based nodes often use both 0 and 1)
send_cli_command - Execute CLI commands on running nodes (requires PyATS); optional console index selects which serial port to use
Interface & Link Management
add_interface_to_node - Add an interface to a node. Returns a list of created interfaces (a single slot request may add multiple interfaces depending on the node type)
get_interfaces_for_node - Get all interfaces for a node
connect_two_nodes - Create a link between two interfaces
get_annotations_for_cml_lab - Get all visual annotations in a lab
add_text_annotation - Add a text annotation
add_rectangle_annotation - Add a rectangle annotation
add_ellipse_annotation - Add an ellipse annotation
add_line_annotation - Add a line annotation
delete_annotation_from_lab - Delete an annotation (prompts for confirmation if client supports it)
Packet Capture (PCAP)
start_packet_capture - Start capturing packets on a link
stop_packet_capture - Stop an active packet capture
check_packet_capture_status - Check capture status and packet count
get_captured_packet_overview - Get summary of captured packets
get_packet_capture_data - Download full PCAP file (base64-encoded for Wireshark/tcpdump)
User & Group Management
get_cml_users - List all CML users
create_cml_user - Create a new user (requires admin)
delete_cml_user - Delete a user (requires admin, prompts for confirmation if client supports it)
get_cml_groups - List all CML groups
create_cml_group - Create a new group (requires admin)
delete_cml_group - Delete a group (requires admin, prompts for confirmation if client supports it)
System Information
get_cml_information - Get CML server version and configuration
get_cml_status - Get system health indicators
get_cml_statistics - Get resource usage and lab/node/link counts
get_cml_licensing_details - Get licensing information and limits
Usage
Once configured, restart your MCP client (e.g., Claude Desktop) and start chatting! The AI assistant now has direct access to your CML server and can help you build and manage network labs through natural conversation.
What Can You Do?
Here are some example prompts to try:
Getting Started:
"Show me all my CML labs"
"What node types are available in CML?"
"Tell me about my CML server status and licensing"
Building Labs:
"Create a new lab called 'OSPF Test Lab'"
"Add two CSR1000v routers and an external connector to my lab"
"Connect Router1's GigabitEthernet1 to Router2's GigabitEthernet1"
Configuration & Testing:
"Configure OSPF area 0 on both routers"
"Start all nodes in the lab"
"Show me the OSPF neighbors on Router1"
"Start a packet capture on the link between the routers"
Complete Workflow Example:
Here's a sequence of prompts that demonstrates building and testing a complete lab:
"Create a new CML lab called 'My Network Lab'"
"Add two IOL routers, an unmanaged switch, and an external connector to this lab"
"Connect the two IOL routers to the unmanaged switch and connect the switch to the external connector"
"Configure the routers so that their connected interfaces have IPs in the 192.0.2.0/24 subnet and configure OSPF on them"
"Start the lab and validate that OSPF is working correctly"
"Add a green box annotation around the two IOL routers with the label 'OSPF Area 0'"
Here's a demo showing it working in Claude Desktop:
Animated demonstration showing Claude Desktop creating a network topology in Cisco Modeling Labs through natural language commands. The sequence shows a user typing prompts to create a lab, add network devices including two IOL routers, an unmanaged switch, and an external connector, then configure OSPF routing between the devices. The interface displays both the chat conversation on the left and the resulting network diagram on the right, with nodes being added and connected in real-time as the AI processes each command.
System Prompt
If your LLM tool supports a system prompt, or you want to provide some richer initial context, here's a good example courtesy of Hank Preston:
You are a network lab assistant specializing in supporting Cisco Modeling Labs (CML). You provide a natural language interface for many common lab activities such as:
Creating new lab
Adding nodes to a lab
Creating interfaces between nodes
Configuring nodes
Creating annotations
You have access to tools to access the CML server.
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
For development setup, testing, and code style information, see DEVELOPMENT.md.
Troubleshooting
Common Issues
"Module not found" or import errors
Make sure you've installed the package with all extras if you need PyATS support:
sh
uvx cml-mcp[pyats] # For uvx installations
SSL Certificate Errors
TLS certificate verification is enabled by default (CML_VERIFY_SSL=true). Because CML ships with a self-signed certificate, verification will fail out of the box with an SSL error. Set CML_VERIFY_SSL=false in your environment configuration to disable verification, or install a CA-signed certificate on your CML server (alternatively, set CA_BUNDLE to a file containing your self-signed certificate).
PyATS command execution fails
Ensure PyATS is installed with cml-mcp[pyats]
Verify PYATS_USERNAME, PYATS_PASSWORD, and PYATS_AUTH_PASS are set correctly
cml-mcp can export a trace span for every tool call, so you can see request latency and failures in an observability backend (Jaeger, Grafana Tempo, Datadog, etc.). It's off by default and adds no overhead until you turn it on.
To enable it, install the opentelemetry extra and set two environment variables:
sh
uvx cml-mcp[opentelemetry]
Need PyATS too? Extras are comma-separated: uvx cml-mcp[pyats,opentelemetry].
examples/skill/cml/SKILL.md - Example agent skill that complements this MCP server with guidance on how to use CML effectively (topology design, layout, operations)
examples/skill/INSTALL.md - How to install the example skill into Claude Code, Claude Desktop, Cursor, and VS Code + GitHub Copilot
