io.github.xorrkaz/cml-mcp

Install

Config snippet generator goes here (5 client tabs)

README

# Model Context Protocol (MCP) Server for Cisco Modeling Labs (CML)

[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/xorrkaz/cml-mcp)

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)](https://www.cisco.com/c/en/us/products/cloud-systems-management/modeling-labs/index.html) 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)](https://modelcontextprotocol.io/docs/getting-started/intro), 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](https://developer.cisco.com/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.
- **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.

## 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:

```json
{
  "mcpServers": {
    "Cisco Modeling Labs (CML)": {
      "command": "uvx",
      "args": ["cml-mcp"],
      "env": {
        "CML_URL": "https://your-cml-server.example.com",
        "CML_USERNAME": "your_username",
        "CML_PASSWORD": "your_password",
        "CML_VERIFY_SSL": "false"
      }
    }
  }
}
```

**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
- Set `CML_VERIFY_SSL` to `"false"` if using self-signed certificates (common in lab environments)

**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](https://github.com/xorrkaz/cml-mcp/blob/main/INSTALLATION.md)

**Where to find your configuration file:**

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

### Requirements

- **Python 3.12 or later**
- **Cisco Modeling Labs (CML) 2.9 or later**
- **[uv](https://docs.astral.sh/uv/)** - Python package manager

## Available MCP Tools

The server provides 47 MCP tools organized into the following categories:

### Lab Management

- **get_cml_labs** - Retrieve labs for a specific user or current user
- **create_empty_lab** - Create a new empty lab with optional metadata
- **create_full_lab_topology** - Create a complete lab from a topology definition
- **modify_cml_lab** - Update lab properties (title, description, notes)
- **start_cml_lab** - Start all nodes in a lab
- **stop_cml_lab** - Stop all nodes in a lab
- **wipe_cml_lab** - Wipe all node data/configurations (requires confirmation)
- **delete_cml_lab** - Delete a lab (requires confirmation)
- **get_cml_lab_by_title** - Find