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模式類型代碼，該代碼受思科專有許可證保護。