cml-mcp

Name: cml-mcp
Author: xorrkaz

作者：xorrkaz16 星标更新：2025-11-17

安装使用来源：spider==github.com

项目介绍

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

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

概述

cml-mcp 是一个为 Cisco Modeling Labs (CML) 设计的 Model Context Protocol (MCP) 服务器实现。它使用 FastMCP 2.0 构建，并旨在为像 Claude Desktop、Claude Code 和 Cursor 这样的 LLM 应用程序提供与 CML 交互的一系列工具。

功能

创建实验室拓扑： 工具用于创建新的实验室并定义网络拓扑。
查询状态： 工具用于检索实验室、节点以及 CML 服务器本身的状态信息。
控制实验室和节点： 工具用于根据需要启动和停止实验室或单个节点。
管理 CML 用户和组： 工具用于列出、创建和删除本地用户和组。
在设备上运行命令： 使用 PyATS，MCP 客户端可以在 CML 实验室中的虚拟设备上执行命令。

要求

Python 3.12+
Cisco Modeling Labs (CML) 2.9 或更高版本
PyATS（可选；用于设备 CLI 命令执行）
uv Python 包/项目管理器

Windows 要求

如果您不想在 CML 中运行的设备上执行 CLI 命令，则只需安装基础的 cml-mcp 包即可。然而，如果需要完全支持，Windows 用户还需要安装 Windows Subsystem for Linux (WSL)，并在 WSL 中安装 Python 和 uv，或者在 Windows 机器上运行 Docker 环境。

快速开始

您可以根据需求和平台选择几种方式来运行此服务器：

方案 1：标准 I/O（stdio）传输

这是传统的运行服务器的方式，其中它通过标准输入/输出流直接与 MCP 客户端通信。

使用 uvx（最简单 - 不支持 CLI）

最简单的方法是使用 uvx，它从 PyPi 下载服务器并在独立环境中运行它。这适用于 Linux、Mac 和 Windows 用户，但不提供 CLI 命令支持。编辑您的客户端配置并添加如下内容。此示例针对 Claude Desktop：

{
  "mcpServers": {
    "Cisco Modeling Labs (CML)": {
      "command": "uvx",
      "args": [
        "cml-mcp"
      ],
      "env": {
        "CML_URL": "<CML_SERVER_URL>",
        "CML_USERNAME": "<CML_SERVER_USERNAME>",
        "CML_PASSWORD": "<CML_SERVER_PASSWORD>"
      }
    }
  }
}

为了在 CML 中运行的设备上执行 CLI 命令，Linux 和 Mac 用户需要将 "args" 更改为 cml-mcp[pyats]。例如：

{
  "mcpServers": {
    "Cisco Modeling Labs (CML)": {
      "command": "uvx",
      "args": [
        "cml-mcp[pyats]"
      ],
      "env": {
        "CML_URL": "<CML_SERVER_URL>",
        "CML_USERNAME": "<CML_SERVER_USERNAME>",
        "CML_PASSWORD": "<CML_SERVER_PASSWORD>",
        "PYATS_USERNAME": "<DEVICE_USERNAME>",
        "PYATS_PASSWORD": "<DEVICE_PASSWORD>",
        "PYATS_AUTH_PASS": "<DEVICE_ENABLE_PASSWORD>"
      }
    }
  }
}

额外的 PYATS 环境变量是必需的，以便让 MCP 服务器知道如何登录到这些正在运行的设备。

希望支持 CLI 命令且使用 Windows Subsystem for Linux (WSL) 的 Windows 用户应进行如下配置：

{
  "mcpServers": {
    "Cisco Modeling Labs (CML)": {
      "command": "wsl",
      "args": [
        "uvx",
        "cml-mcp[pyats]"
      ],
      "env": {
        "CML_URL": "<CML_SERVER_URL>",
        "CML_USERNAME": "<CML_SERVER_USERNAME>",
        "CML_PASSWORD": "<CML_SERVER_PASSWORD>",
        "PYATS_USERNAME": "<DEVICE_USERNAME>",
        "PYATS_PASSWORD": "<DEVICE_PASSWORD>",
        "PYATS_AUTH_PASS": "<DEVICE_ENABLE_PASSWORD>",
        "WSLENV": "CML_URL/u:CML_USERNAME/u:CML_PASSWORD/u:PYATS_USERNAME/u:PYATS_PASSWORD/u:PYATS_AUTH_PASS/u:PYATS_AUTH_PASS/u"
      }
    }
  }
}

希望支持 CLI 命令且使用 Docker 的 Windows（以及 Mac 和 Linux 用户）应进行如下配置：

{
  "mcpServers": {
    "Cisco Modeling Labs (CML)": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--pull",
        "always",
        "-e",
        "CML_URL",
        "-e",
        "CML_USERNAME",
        "-e",
        "CML_PASSWORD",
        "-e",
        "PYATS_USERNAME",
        "-e",
        "PYATS_PASSWORD",
        "-e",
        "PYATS_AUTH_PASS",
        "xorrkaz/cml-mcp:latest"
      ],
      "env": {
        "CML_URL": "<CML_SERVER_URL>",
        "CML_USERNAME": "<CML_SERVER_USERNAME>",
        "CML_PASSWORD": "<CML_SERVER_PASSWORD>",
        "PYATS_USERNAME": "<DEVICE_USERNAME>",
        "PYATS_PASSWORD": "<DEVICE_PASSWORD>",
        "PYATS_AUTH_PASS": "<DEVICE_ENABLE_PASSWORD>"
      }
    }
  }
}

使用 FastMCP CLI

另一种方法是使用 FastMCP CLI 将服务器安装到您喜欢的客户端中。FastMCP CLI 支持 Claude Desktop、Claude Code、Cursor 和手动 JSON 生成。要使用 FastMCP，请执行以下操作：

克隆此仓库：

git clone https://github.com/xorrkaz/cml-mcp.git

切换目录到克隆的仓库。
运行 uv sync 来安装所有正确的依赖项，包括 FastMCP 2.0。注意： 在 Linux 和 Mac 上，运行 uv sync --all-extras 以获得 CLI 命令支持。

创建一个 .env 文件，设置以下变量：

CML_URL=<CML_SERVER_URL>
CML_USERNAME=<CML_SERVER_USERNAME>
CML_PASSWORD=<CML_SERVER_PASSWORD>
# 为了运行命令，这是可选的
PYATS_USERNAME=<DEVICE_USERNAME>
PYATS_PASSWORD=<DEVICE_PASSWORD>
PYATS_AUTH_PASS=<DEVICE_ENABLE_PASSWORD>

运行 FastMCP CLI 命令来安装服务器。例如：

fastmcp install claude-desktop src/cml_mcp/server.py:server_mcp --project `realpath .` --env-file .env

方案 2：HTTP 传输（流式传输）

服务器现在支持 HTTP 流式传输，这对于将 MCP 服务器作为可以被多个客户端访问的独立服务运行非常有用，或者当您想在容器化或远程环境中运行时。这种模式使用 HTTP 服务器发送事件（SSE）进行实时通信。

运行 HTTP 服务器

要在 HTTP 模式下运行服务器，请将 CML_MCP_TRANSPORT 环境变量设置为 http。您还可以配置绑定地址和端口。

首先，安装包：

uv venv
source .venv/bin/activate
uv pip install cml-mcp # 或 cml-mcp\[pyats] 以获得 CLI 命令支持

或者对于开发，克隆仓库并同步依赖项：

git clone https://github.com/xorrkaz/cml-mcp.git
cd cml-mcp
uv sync # 添加 --all-extras 以获得 CLI 命令支持

然后使用 uvicorn 运行服务器：

# 设置环境变量
export CML_URL=<CML_SERVER_URL>
export CML_MCP_TRANSPORT=http
export CML_MCP_BIND=0.0.0.0  # 可选，默认为 0.0.0.0
export CML_MCP_PORT=9000     # 可选，默认为 9000

# 使用 uvicorn 运行服务器
uvicorn cml_mcp.server:app --host 0.0.0.0 --port 2000

或者创建一个 .env 文件，包含这些设置：

CML_URL=<CML_SERVER_URL>
CML_MCP_TRANSPORT=http
CML_MCP_BIND=0.0.0.0
CML_MCP_PORT=9000

然后运行：

cml-mcp

服务器将启动并监听 http://0.0.0.0:9000 的 HTTP 连接。

HTTP 模式的认证

使用 HTTP 传输时，认证处理方式不同于 stdio 模式：

CML 凭证：而不是通过环境变量设置，CML 凭证通过 X-Authorization HTTP 头提供，使用基本认证格式。
PyATS 凭证：为了执行 CLI 命令，PyATS 凭证可以通过 X-PyATS-Authorization 头（基本认证）提供，启用密码通过 X-PyATS-Enable 头提供。

示例头：

X-Authorization: Basic <base64_encoded_cml_username:cml_password>
X-PyATS-Authorization: Basic <base64_encoded_device_username:device_password>
X-PyATS-Enable: Basic <base64_encoded_enable_password>

配置 MCP 客户端以使用 HTTP

要使用 HTTP 服务器与 MCP 客户端一起工作，您需要使用 mcp-remote 工具连接到 HTTP 端点。大多数 MCP 客户端如 Claude Desktop 本身不支持 HTTP 流式传输，因此 mcp-remote 作为客户端（期望 stdio）和 HTTP 服务器之间的桥梁。此桥梁需要在客户端机器上安装 Node.js。Node.js 包含 npx 工具，允许您在一个专用环境中运行 JavaScript/TypeScript 应用程序。

向您的 MCP 客户端配置添加以下内容（例如，Claude Desktop 的 claude_desktop_config.json）：

{
  "mcpServers": {
    "Cisco Modeling Labs (CML)": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://<server_host>:9000/mcp",
        "--header",
        "X-Authorization: Basic <base64_encoded_cml_credentials>",
        "--header",
        "X-PyATS-Authorization: Basic <base64_encoded_device_credentials>"
      ]
    }
  }
}

替换占位符为实际值：

<server_host>：您的 HTTP 服务器运行的主机名或 IP 地址
<base64_encoded_cml_credentials>：CML 的 username:password 的 Base64 编码
<base64_encoded_device_credentials>：设备访问的 username:password 的 Base64 编码

示例：

{
  "mcpServers": {
    "Cisco Modeling Labs (CML)": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://192.168.10.210:8443/mcp",
        "--header",
        "X-Authorization: Basic <base64_encoded_cml_credentials>",
        "--header",
        "X-PyATS-Authorization: Basic <base64_encoded_device_credentials>"
      ]
    }
  }
}

注意：当使用自签名证书的 HTTPS 时，您需要通过添加 env 部分来禁用 TLS 证书验证：

{
  "mcpServers": {
    "Cisco Modeling Labs (CML)": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://192.168.10.210:8443/mcp",
        "--header",
        "X-Authorization: Basic <base64_encoded_cml_credentials>",
        "--header",
        "X-PyATS-Authorization: Basic <base64_encoded_device_credentials>"
      ],
      "env": {
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

要将您的凭证编码为 Base64：

Linux/Mac：

# 对于 CML 凭证
echo -n "username:password" | base64

# 对于设备凭证
echo -n "device_username:device_password" | base64

# 对于启用密码（如有需要）
echo -n "enable_password" | base64

Windows（使用 WSL）：

wsl bash -c 'echo -n "username:password" | base64'
wsl bash -c 'echo -n "device_username:device_password" | base64'
wsl bash -c 'echo -n "enable_password" | base64'

或者，您可以使用在线 Base64 编码器或 PowerShell：

[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("username:password"))

如果您需要指定启用密码，请添加另一个头：

"--header",
"X-PyATS-Enable: Basic <base64_encoded_enable_password>"

使用 HTTP 传输的 Docker

您也可以使用 Docker 在 HTTP 模式下运行服务器：

docker run -d \
  --rm \
  --name cml-mcp \
  -p 9000:9000 \
  -e CML_URL=<CML_SERVER_URL> \
  -e CML_MCP_TRANSPORT=http \
  xorrkaz/cml-mcp:latest

这会公开 HTTP 服务器在端口 9000，允许外部 MCP 客户端连接。

使用

这些工具应该会自动出现在您的 MCP 客户端中，您可以与 LLM 聊天，让它根据需要调用工具。例如，以下提示序列很好地展示了服务器的一些能力：

创建一个新的 CML 实验室，名为“Joe 的 MCP 实验室”。
向这个实验室添加两个 IOL 节点、一个未管理的交换机和一个外部连接器。
将两个 IOL 节点连接到未管理的交换机，再将未管理的交换机连接到外部连接器。
配置路由器，使它们连接的接口具有 192.0.2.0/24 子网的 IP 地址。在它们上配置 OSPF。然后启动实验室并验证 OSPF 是否正常工作。
在两个 IOL 节点周围添加一个框注释，表明它们使用 OSPF。使其成为一个绿色框。

这里是一个必有的演示 GIF，展示它在 Claude Desktop 中的工作情况：

动画演示显示 Claude Desktop 通过自然语言命令在 Cisco Modeling Labs 中创建网络拓扑。该序列显示了一个用户键入提示以创建实验室，添加网络设备，包括两个 IOL 路由器、一个未管理的交换机和一个外部连接器，然后在设备之间配置 OSPF 路由。界面显示了左侧的聊天对话和右侧的结果网络图，随着 AI 处理每个命令，节点被实时添加和连接。

系统提示

如果您的 LLM 工具支持系统提示，或者您想要提供一些更丰富的初始上下文，这里有一个来自 Hank Preston 的好例子：

您是一位专注于支持 Cisco Modeling Labs (CML) 的网络实验室助手。您提供了许多常见实验室活动的自然语言接口，例如：

创建新实验室

向实验室添加节点

在节点之间创建接口

配置节点

创建注释

您有权访问工具以访问 CML 服务器。

许可

本项目的 MCP 服务器部分在 BSD 2-Clause "简化"许可下发布。然而，它利用了 CML 自身的 pydantic 模式类型代码，后者受专有 Cisco 许可保护。