shield_lock
金大哥
联系我们
← 返回 MCP 目录
public公开dns本地运行

cml-mcp

Cisco Modeling Labs (CML) 的模型上下文协议 (MCP) 服务器，为Claude Desktop等LLM应用提供与CML交互的工具，支持创建网络拓扑、查询状态、控制设备和管理用户等功能。

article

README

🚀 思科建模实验室（CML）的模型上下文协议（MCP）服务器

本项目是专为思科建模实验室（CML）设计的模型上下文协议（MCP）服务器，借助它可以让LLM应用（如Claude Desktop、Claude Code和Cursor）与CML进行交互，实现创建实验室拓扑、查询状态、控制实验室和节点等功能。

🚀 快速开始

你可以根据自身需求和平台，选择以下几种方式来运行此服务器：

选项1：标准输入输出（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": "<URL_OF_CML_SERVER>",
        "CML_USERNAME": "<USERNAME_ON_CML_SERVER>",
        "CML_PASSWORD": "<PASSWORD_ON_CML_SERVER>",
        "CML_VERIFY_SSL": "false",
        "DEBUG": "false"
      }
    }
  }
}

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

{
  "mcpServers": {
    "Cisco Modeling Labs (CML)": {
      "command": "uvx",
      "args": [
        "cml-mcp[pyats]"
      ],
      "env": {
        "CML_URL": "<URL_OF_CML_SERVER>",
        "CML_USERNAME": "<USERNAME_ON_CML_SERVER>",
        "CML_PASSWORD": "<PASSWORD_ON_CML_SERVER>",
        "CML_VERIFY_SSL": "false",
        "PYATS_USERNAME": "<DEVICE_USERNAME>",
        "PYATS_PASSWORD": "<DEVICE_PASSWORD>",
        "PYATS_AUTH_PASS": "<DEVICE_ENABLE_PASSWORD>",
        "DEBUG": "false"
      }
    }
  }
}

需要额外的PYATS环境变量，以便MCP服务器知道如何登录正在运行的设备。 使用Windows子系统Linux（WSL）且需要CLI命令支持的Windows用户应进行如下配置：

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

使用Docker且需要CLI命令支持的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",
        "-e",
        "CML_VERIFY_SSL",
        "-e",
        "DEBUG",
        "xorrkaz/cml-mcp:latest"
      ],
      "env": {
        "CML_URL": "<URL_OF_CML_SERVER>",
        "CML_USERNAME": "<USERNAME_ON_CML_SERVER>",
        "CML_PASSWORD": "<PASSWORD_ON_CML_SERVER>",
        "CML_VERIFY_SSL": "false",
        "PYATS_USERNAME": "<DEVICE_USERNAME>",
        "PYATS_PASSWORD": "<DEVICE_PASSWORD>",
        "PYATS_AUTH_PASS": "<DEVICE_ENABLE_PASSWORD>",
        "DEBUG": "false"
      }
    }
  }
}

使用FastMCP CLI

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

  1. 克隆此仓库：
git clone https://github.com/xorrkaz/cml-mcp.git
  1. 切换到克隆的仓库目录。
  2. 运行uv sync以安装所有正确的依赖项，包括FastMCP 2.0。注意：在Linux和Mac上，运行uv sync --all-extras以获得CLI命令支持。
  3. 创建一个.env文件，并设置以下变量：
CML_URL=<URL_OF_CML_SERVER>
CML_USERNAME=<USERNAME_ON_CML_SERVER>
CML_PASSWORD=<PASSWORD_ON_CML_SERVER>
CML_VERIFY_SSL=false  # 设置为true以验证SSL证书
DEBUG=false  # 设置为true以启用调试日志
# 运行命令时可选
PYATS_USERNAME=<DEVICE_USERNAME>
PYATS_PASSWORD=<DEVICE_PASSWORD>
PYATS_AUTH_PASS=<DEVICE_ENABLE_PASSWORD>
  1. 运行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=<URL_OF_CML_SERVER>
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 9000

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

CML_URL=<URL_OF_CML_SERVER>  # 在HTTP模式下，如果使用 X-CML-URL 头则可选
CML_MCP_TRANSPORT=http
CML_MCP_BIND=0.0.0.0
CML_MCP_PORT=9000
CML_VERIFY_SSL=false  # 设置为true以验证SSL证书
DEBUG=false  # 设置为true以启用调试日志
# 支持多个CML主机时，使用以下之一：
CML_ALLOWED_URLS=https://cml1.example.com,https://cml2.example.com  # 逗号分隔的列表
# 或者
CML_URL_PATTERN=^https://cml\.example\.com  # 正则表达式模式

然后运行：

cml-mcp

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

HTTP模式下的身份验证

使用HTTP传输时，身份验证的处理方式与stdio模式不同：

  • CML凭证：CML凭证不是通过环境变量设置，而是通过X-AuthorizationHTTP头以基本身份验证格式提供。
  • PyATS凭证：对于CLI命令执行，PyATS凭证可以通过X-PyATS-Authorization头（基本身份验证）提供，启用密码通过X-PyATS-Enable头提供。
  • 多个CML主机：在HTTP模式下运行时，客户端可以通过提供X-CML-URL头连接到不同的CML服务器。为了安全起见，你必须通过CML_ALLOWED_URLS环境变量（逗号分隔的列表）或CML_URL_PATTERN（正则表达式模式）配置允许的URL。 示例头信息：
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>
X-CML-URL: https://cml-server.example.com

为HTTP配置MCP客户端

要将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的Base64编码的username:password。
  • <base64_encoded_device_credentials>：设备访问的Base64编码的username:password。 示例：
{
  "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=<URL_OF_CML_SERVER> \
  -e CML_MCP_TRANSPORT=http \
  xorrkaz/cml-mcp:latest

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

✨ 主要特性

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

📦 安装指南

系统要求

  • Python 3.12+
  • 思科建模实验室（CML）2.9或更高版本
  • PyATS（可选；用于设备CLI命令执行）
  • uv Python包/项目管理器

Windows额外要求

如果你不想在CML中运行的设备上运行CLI命令，除了安装基本的cml-mcp包之外，你不需要做任何其他事情。但是，如果你需要完整支持，Windows用户还需要安装带有Python和uv的Windows子系统Linux（WSL），或者在Windows机器上运行Docker环境。

💻 使用示例

工具应该会自动显示在你的MCP客户端中，你可以与大语言模型（LLM）聊天，让它根据需要调用工具。例如，以下一系列提示很好地展示了服务器的一些功能：

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

以下是一个展示它在Claude Desktop中工作的演示GIF： 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.

系统提示

如果你的LLM工具支持系统提示，或者你想提供一些更丰富的初始上下文，以下是一个由Hank Preston提供的很好的示例：

你是一位专门支持思科建模实验室（CML）的网络实验室助手。你为许多常见的实验室活动提供自然语言接口，例如：

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

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

📄 许可证

本项目的MCP服务器部分根据BSD 2条款“简化”许可证许可。但是，它利用了CML本身的pydantic模式类型代码，该代码受思科专有许可证保护。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端