Cml MCP

🚀 思科建模实验室（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

2. 切换到克隆的仓库目录。
3. 运行uv sync以安装所有正确的依赖项，包括FastMCP 2.0。注意：在Linux和Mac上，运行uv sync --all-extras以获得CLI命令支持。
4. 创建一个.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>

5. 运行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：

系统提示

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

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

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

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

📄 许可证

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