Cisco Modeling Labs CML

Cisco Modeling Labs (CML) 的 Model Context Protocol (MCP) 服务

mcp-name: io.github.xorrkaz/cml-mcp

概述

cml-mcp 为你的网络实验室带来 AI 助手的强大功能！借助此工具，你可以通过 Claude Desktop、Claude Code 和 Cursor 等 AI 应用，使用自然语言与 Cisco Modeling Labs (CML) 交互。

无需逐个点击菜单或编写脚本，只需用通俗的英语告诉 AI 你想做什么，例如“创建一个包含两台路由器并配置 OSPF 的新实验”或“显示 Router1 上的运行配置”，然后就能看到它自动完成操作。

这是通过 Model Context Protocol (MCP) 实现的。MCP 是一种让 AI 应用与外部工具和服务交互的标准。你可以把它想象成让 AI 助手直接连接到你的 CML 服务。

功能

• 创建实验拓扑： 提供从头创建实验并定义网络拓扑，或使用完整拓扑定义的工具。
• 查询状态： 提供获取实验、节点、链路、注释以及 CML 服务本身的详细状态信息的工具。
• 控制实验和节点： 根据需要启动、停止或清除实验或单个节点。
• 管理 CML 用户和组： 提供列出、创建和删除本地用户及组的工具（需要管理员权限）。
• 可视化注释： 在实验拓扑中添加可视元素（文本、矩形、椭圆、线条），用于文档记录和整理。
• 链路管理： 连接节点、配置链路条件（带宽、延迟、抖动、丢包）并控制链路状态。
• 数据包捕获： 启动、停止和获取网络链路上的数据包捕获（PCAP），以便使用 Wireshark 或其他工具分析流量。
• 节点配置： 配置节点启动配置，并向正在运行的设备发送 CLI 命令。
• 在设备上运行命令： MCP 客户端可使用 PyATS 在 CML 实验中的虚拟设备上执行命令。
• 控制台日志访问： 获取正在运行的节点的控制台日志，用于故障排除和监控，并支持选择特定的串行控制台端口。
• 模块化架构： 工具按逻辑模块（实验、节点、链路、pcap 等）组织，便于维护和扩展。
• 访问控制列表（HTTP 模式）： 在 HTTP 传输模式下运行时，可以使用基于 YAML 的 ACL 配置文件，限制用户可访问的工具。
• 可观测性： 可选的 OpenTelemetry 跟踪会将每次工具调用的 span 导出到任何兼容 OTLP 的后端（Jaeger、Grafana Tempo、Datadog 等）。

快速入门

安装

最简单的入门方式是将 uvx 与 Claude Desktop（或其他兼容 MCP 的客户端）搭配使用。uvx 工具会自动下载并运行服务，无需手动安装。

配置： 找到并编辑 Claude Desktop 配置文件（claude_desktop_config.json）。添加以下内容：

{
    "mcpServers": {                                                               
        "Cisco Modeling Labs CML": {                                                                
          "type": "stdio",                                                          
          "command": "uvx",
          "args": [                                                                 
            "cml-mcp"                                                        
          ],                                                                        
          "env": {
            "CML_URL": "{CML_URL}",                           
            "CML_USERNAME": "{CML_USERNAME}",                                                 
            "CML_PASSWORD": "{CML_PASSWORD}!",
            "CML_VERIFY_SSL": "true"
          }                                                                         
        }
    }
}

重要： 请将占位值替换为实际的 CML 服务详细信息：

• CML_URL：CML 服务地址（例如，https://cml.example.com 或 https://10.10.20.50）
• CML_USERNAME 和 CML_PASSWORD：CML 登录凭据
• CML_VERIFY_SSL：TLS 证书验证现在默认为 "true"。CML 开箱即用时附带自签名证书，因此大多数用户需要将其设为 "false"。只有在 CML 服务上安装了由 CA 签名的证书（或将 CA_BUNDLE 指向包含自签名证书的文件）时，才保留 "true"。

提示

uvx 提示“找不到命令”？ Claude Desktop 等 MCP 客户端在受限环境中运行，不一定会继承 shell 的 PATH。如果找不到 uvx，请在 "command" 字段中使用其完整路径。要查找路径，请在 macOS/Linux 的终端中运行 which uvx，或在 Windows 的命令提示符中运行 where uvx（例如，macOS 上的 "/Users/alice/.local/bin/uvx"，Windows 上的 "C:\Users\alice\.local\bin\uvx.exe"）。MCP 配置中使用的 uv、npx 或任何其他命令也同样如此。

需要更多功能？

• 如需执行设备 CLI 命令，请在 args 中使用 cml-mcp[pyats]，而不是 cml-mcp
• 如需了解 Docker、Windows（WSL）或 HTTP 服务模式，请参阅 INSTALLATION.md

配置文件位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

要求

• Python 3.12、3.13 或 3.14
• Cisco Modeling Labs（CML）2.9 或更高版本
• uv - Python 包管理器

可用的 MCP 工具

该服务提供 51 个 MCP 工具，分为以下类别：

实验室管理

• get_cml_labs - 获取指定用户或当前用户的实验室
• create_empty_lab - 创建空实验室，可选添加元数据
• create_full_lab_topology - 根据拓扑定义创建完整实验室
• modify_cml_lab - 更新实验室属性（标题、描述、备注）
• set_cml_lab_permissions - 配置组/用户访问权限（LAB_ADMIN、LAB_EDIT、LAB_EXEC、LAB_VIEW）
• start_cml_lab - 启动实验室中的所有节点
• stop_cml_lab - 停止实验室中的所有节点
• wipe_cml_lab - 清除所有节点数据/配置（如果客户端支持，则会请求确认）
• delete_cml_lab - 删除实验室（如果客户端支持，则会请求确认）
• get_cml_lab_by_title - 按标题查找实验室
• download_lab_topology - 将实验室拓扑下载为 YAML 文件
• clone_cml_lab - 克隆实验室，可选设置新标题

节点管理

• get_cml_node_definitions - 列出可用的节点类型
• get_node_definition_detail - 获取特定节点类型的详细信息
• add_node_to_cml_lab - 向实验室添加节点
• get_nodes_for_cml_lab - 获取实验室中的所有节点及其运行数据
• configure_cml_node - 设置节点启动配置
• start_cml_node - 启动指定节点
• stop_cml_node - 停止指定节点
• wipe_cml_node - 清除节点数据（如果客户端支持，会请求确认）
• delete_cml_node - 删除节点（如果客户端支持，会请求确认）
• get_console_log - 获取节点的控制台输出历史记录；可选的 console 索引用于选择串行端口（默认为 0；基于 Docker 的节点通常同时使用 0 和 1）
• send_cli_command - 在运行中的节点上执行 CLI 命令（需要 PyATS）；可选的 console 索引用于选择要使用的串行端口

接口与链路管理

• add_interface_to_node - 向节点添加接口。返回已创建接口的列表（根据节点类型，一个插槽请求可能会添加多个接口）
• get_interfaces_for_node - 获取节点的所有接口
• connect_two_nodes - 在两个接口之间创建链路
• get_all_links_for_lab - 获取实验室中的所有链路
• apply_link_conditioning - 配置网络条件（带宽、延迟、抖动、丢包）
• start_cml_link - 启用链路上的连接
• stop_cml_link - 禁用链路上的连接

注释（可视元素）

• get_annotations_for_cml_lab - 获取实验室中的所有可视注释
• add_text_annotation - 添加文本注释
• add_rectangle_annotation - 添加矩形注释
• add_ellipse_annotation - 添加椭圆注释
• add_line_annotation - 添加线条注释
• delete_annotation_from_lab - 删除注释（如果客户端支持，会请求确认）

数据包捕获（PCAP）

• start_packet_capture - 开始捕获链路上的数据包
• stop_packet_capture - 停止正在进行的数据包捕获
• check_packet_capture_status - 检查捕获状态和数据包数量
• get_captured_packet_overview - 获取已捕获数据包的摘要
• get_packet_capture_data - 下载完整的 PCAP 文件（以 Base64 编码，可用于 Wireshark/tcpdump）

用户与组管理

• get_cml_users - 列出所有 CML 用户
• create_cml_user - 创建新用户（需要管理员权限）
• delete_cml_user - 删除用户（需要管理员权限；如果客户端支持，会请求确认）
• get_cml_groups - 列出所有 CML 组
• create_cml_group - 创建新组（需要管理员权限）
• delete_cml_group - 删除组（需要管理员权限；如果客户端支持，会请求确认）

系统信息

• get_cml_information - 获取 CML 服务版本和配置
• get_cml_status - 获取系统运行状况指标
• get_cml_statistics - 获取资源使用情况以及实验室/节点/链路数量
• get_cml_licensing_details - 获取许可信息和限制

使用方法

配置完成后，重启 MCP 客户端（例如 Claude Desktop），然后开始对话！AI 助手现在可以直接访问你的 CML 服务，并通过自然对话帮助你构建和管理网络实验室。

可以做什么？

以下是一些可尝试的示例提示词：

入门：

• “显示我的所有 CML 实验”
• “CML 中有哪些节点类型？”
• “介绍一下我的 CML 服务状态和许可信息”

构建实验：

• “创建一个名为 ‘OSPF Test Lab’ 的新实验”
• “在我的实验中添加两台 CSR1000v 路由器和一个外部连接器”
• “将 Router1 的 GigabitEthernet1 连接到 Router2 的 GigabitEthernet1”

配置与测试：

• “在两台路由器上配置 OSPF 区域 0”
• “启动实验中的所有节点”
• “显示 Router1 上的 OSPF 邻居”
• “在两台路由器之间的链路上启动数据包捕获”

完整工作流示例：

以下是一系列提示词，演示如何构建并测试一个完整的实验：

1. “创建一个名为 ‘My Network Lab’ 的新 CML 实验”
2. “在此实验中添加两台 IOL 路由器、一台非托管交换机和一个外部连接器”
3. “将两台 IOL 路由器连接到非托管交换机，再将交换机连接到外部连接器”
4. “配置路由器，使其已连接的接口使用 192.0.2.0/24 子网中的 IP 地址，并在它们上面配置 OSPF”
5. “启动实验并验证 OSPF 是否正常工作”
6. “在两台 IOL 路由器周围添加一个绿色方框标注，标签为 ‘OSPF Area 0’”

以下演示展示了它在 Claude Desktop 中的运行效果：

系统提示词

如果你的大模型工具支持系统提示词，或者你想提供更丰富的初始上下文，以下是 Hank Preston 提供的一个不错示例：

你是一名专门支持 Cisco Modeling Labs（CML）的网络实验助手。你通过自然语言界面支持许多常见的实验活动，例如：

• 创建新实验
• 向实验添加节点
• 在节点之间创建接口
• 配置节点
• 创建标注

你可以使用访问 CML 服务的工具。

参与贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。

有关开发环境设置、测试和代码风格的信息，请参阅 DEVELOPMENT.md。

故障排除

常见问题

“Module not found” 或导入错误

如果需要 PyATS 支持，请确保安装了包含所有额外依赖项的软件包：

uvx cml-mcp[pyats]  # For uvx installations

SSL 证书错误

TLS 证书验证默认启用（CML_VERIFY_SSL=true）。由于 CML 随附自签名证书，默认情况下验证会失败并出现 SSL 错误。请在环境配置中设置 CML_VERIFY_SSL=false 以禁用验证，或者在 CML 服务上安装由 CA 签名的证书（也可以将 CA_BUNDLE 设置为包含自签名证书的文件）。

PyATS 命令执行失败

1. 确保已通过 cml-mcp[pyats] 安装 PyATS
2. 检查 PYATS_USERNAME、PYATS_PASSWORD 和 PYATS_AUTH_PASS 是否已正确设置
3. 在 Windows 上，使用 WSL 或 Docker 来支持 PyATS

如需更多故障排除帮助，请参阅 INSTALLATION.md。

可观测性

cml-mcp 可以为每次工具调用导出一个跟踪 Span，让你在可观测性后端（Jaeger、Grafana Tempo、Datadog 等）中查看请求延迟和失败情况。默认情况下，此功能处于关闭状态，启用前不会产生任何开销。

要启用此功能，请安装 opentelemetry extra 并设置两个环境变量：

uvx cml-mcp[opentelemetry]

还需要 PyATS 吗？Extras 以逗号分隔：uvx cml-mcp[pyats,opentelemetry]。

"env": {
    "ENABLE_OTEL": "true",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317"
}

有关完整的设置详情（包括如何运行本地跟踪查看器），请参阅 INSTALLATION.md。

获取帮助

• 查看 Issues 页面，了解已知问题
• 查看 CONTRIBUTING.md，了解如何报告错误

文档

• INSTALLATION.md - 适用于所有平台和传输模式的详细安装说明
• DEVELOPMENT.md - 开发环境设置、测试和贡献指南
• CONTRIBUTING.md - 如何为项目做贡献
• examples/skill/cml/SKILL.md - 示例 Agent 技能，通过提供有效使用 CML 的指导（拓扑设计、布局、操作）来补充此 MCP 服务
• examples/skill/INSTALL.md - 如何将示例技能安装到 Claude Code、Claude Desktop、Cursor 和 VS Code + GitHub Copilot 中

许可证

本项目的 MCP 服务部分采用 BSD 2-Clause "Simplified" License 授权。不过，它使用了 CML 本身的 pydantic 架构类型代码，该代码受 Cisco 专有许可证约束。