# 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

```bash
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`:

```toml
[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

```bash
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

```json
{
  "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:

```json
{
  "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`.