Skip to main content
Glama
Sign In
net-cli-mcp

net-cli-mcp

by gufeihong
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

net-cli-mcp

面向网络工程师的 MCP 服务 + 实时 Web 控制台：让 AI 用自然语言管理 Cisco / 华为 / H3C 交换机，命令和回显在同一个窗口里同步可见。

把原来两个只支持单一厂商的工具（cisco-cli-mcp / h3c-cli-mcp）合并重写，补齐了华为 VRP 支持、多厂商自动识别、串口与 SSH 通道，并加了一个 SSE 实时串流窗口——AI 下的每一条命令、设备的每一块回显，你都能亲眼看到。

status status license

为什么需要它

痛点

这个项目怎么解决

AI 直接连交换机，下了什么命令你不知道

Web 控制台实时串流：tx（命令）/ rx（回显）逐块推送，命令带来源徽标

同一套提示符正则在华为设备上不匹配

多厂商识别：banner 关键字 → display version 精判 → 提示符兜底，三级判定

长回显卡在 ---- More ----，下一条命令首字符被吃掉

发送前探测残留并自动翻完页；执行中遇分页标记自动续翻

只能 Telnet，设备没网口时无计可施

Telnet / SSH / Console 串口三种通道，共用同一套会话抽象与命令执行逻辑

输出里混着 ANSI 控制序列，日志没法看

统一净化：剔除 \x1b[42D 等序列与页标记

Related MCP server: NetPilot-MCP

架构

┌─────────────────────┐        ┌──────────────────────┐
│  MCP 客户端          │        │  浏览器窗口            │
│  (Claude / WorkBuddy)│        │  http://127.0.0.1:8199│
└──────────┬──────────┘        └───────────┬──────────┘
           │ MCP (stdio)                   │ SSE + HTTP
           ▼                               ▼
┌────────────────────────────────────────────────────────┐
│  server.py  ──  会话管理 / 厂商识别 / 提示符 / 翻页 / 净化  │
│  console/app.py  ── 事件总线 · 流式执行 · 历史落盘          │
└────────────────────────┬───────────────────────────────┘
                         │ reader.read(n) / writer.write()
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
   telnetlib3        paramiko          pyserial
   Telnet :23        SSH :22          COMx @9600
        └────────────────┼────────────────┘
                         ▼
              Cisco IOS / Huawei VRP / H3C Comware

三种传输都以 reader.read() / writer.write() / drain() / close() 对齐，所以会话逻辑只有一份。

快速开始

git clone https://github.com/gufeihong/AI-net-cli-mcp.git
cd AI-net-cli-mcp

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt

pyserial 不装 → 串口工具自动隐藏；paramiko 不装 → SSH 工具自动隐藏，其余功能不受影响。

1) 注册到 MCP 客户端

把 mcp-config.example.json 的内容合并进你的客户端配置：

  • Claude Desktop：claude_desktop_config.json

  • WorkBuddy：~/.workbuddy/mcp.json

{
  "mcpServers": {
    "net-cli-mcp": {
      "command": "python",
      "args": ["C:/tools/net-cli-mcp/server.py"]
    }
  }
}

重启客户端后可见 7 个工具：

工具

说明

telnet_connect(host, port, username, password, timeout)

建立 Telnet 会话，自动登录 / 关分页 / 识别厂商

telnet_execute(session_id, command, wait_ms)

下发命令，返回净化后的回显、当前提示符与视图

telnet_list_sessions()

列出活动会话

telnet_disconnect(session_id)

断开并释放

serial_connect(port, baudrate, ...)

Console 串口会话（USB 转串口）

serial_list_ports()

枚举本机串口

ssh_connect(host, port, username, password, timeout)

SSH 会话（paramiko，invoke_shell 通道）

一串自然语言的典型往返：

你：连一下 192.168.1.1，看看有哪些端口是 UP 的
AI：telnet_connect(192.168.1.1, username=..., password=...)
    → vendor=huawei, prompt=<SW1>, view=user-view
    telnet_execute("display interface brief | include up")
    → 24 个 GE 口 UP

2) 打开实时控制台

cd console
python app.py
# 或双击 start-console.bat（Windows）

浏览器打开 http://127.0.0.1:8199。窗口特性：

  • 逐块串流：命令下发与回显实时推送，不是执行完才一次性返回

  • 视觉高亮：IP / 接口名 / 数字 / UP / DOWN / MAC / 时间戳 / 配置关键字 / 报错分色显示，可一键开关

  • 字号可调：12–30px，A+ / A− 或 Ctrl+滚轮，localStorage 记忆

  • 命令行交互：窗口里直接敲命令，走同一条会话；↑↓ 翻历史，Ctrl+L 清屏

  • 来源徽标：AI 发的命令带 [来源] 标记，和手敲的区分开

  • 历史落盘：console/logs/<host>-<时间>.jsonl，一次会话一个文件，便于复盘

  • 只监听 127.0.0.1，不对外暴露

安全加固（可选入口）

默认的 server.py / console/app.py 不做任何拦截——它假设"你会盯着 AI 下的每条命令"。如果做不到（把设备交给 Agent、夜里跑批量巡检、多人共用），改用加固入口：

场景

入口

MCP 客户端

python secure_server.py

浏览器控制台

python secure_console.py

自测（不连设备）

python selftest.py

加固内容：

  • 只读白名单：display / show / ping / tracert 等前缀免审批，可带 | include / exclude / begin 过滤段

  • 写操作需审批码：NETCLI_APPROVAL_SECRET 只在服务端进程环境里，Agent 通过 MCP/HTTP 拿不到；报错不会回显它

  • 目标白名单：NETCLI_ALLOWED_HOSTS 支持精确主机名、IP、CIDR，且不做 DNS 解析

  • API 令牌：NETCLI_API_TOKEN，页面自动下发 HttpOnly Cookie，EventSource 与 fetch 无需改前端

  • 输出脱敏：password irreversible-cipher $1c$…、SNMP 社区串、shared-key、%^%#…%^%# 一律打码，SSE 广播前同样处理

  • JSONL 审计：谁、在哪个会话、发了什么命令、是否经过审批，全部落盘（已脱敏）

export NETCLI_APPROVAL_SECRET='换成你自己的审批码'
export NETCLI_ALLOWED_HOSTS="192.168.10.0/24"
export NETCLI_AUDIT_LOG="$HOME/.local/state/net-cli-mcp/audit.jsonl"
python secure_console.py

启动时会打印 policy=guarded approval=secret secret=set，用来确认保护真的挂上了。完整策略表、审批码的残余风险与边界说明见 docs/security-hardening.md。

加固层只能降低"AI 误操作"的概率，设备侧的 AAA/RBAC 才是真边界。生产核心设备建议给自动化单独开只读账号，写操作走人工。

HTTP API（给 Agent / 脚本用）

控制台同时是一个极简的 HTTP 桥，任何能发 HTTP 的程序都能驱动它——这是把网络设备能力挂到自研 Agent 上最省事的路径。

方法

路径

说明

GET

/api/status

当前连接状态：host / vendor / prompt / view

GET

/api/serialports

枚举串口

GET

/api/stream

SSE 事件流（tx / rx / session / prompt / err）

POST

/api/connect

{transport: telnet|ssh|serial, host, port, username, password}

POST

/api/exec

{command, wait_ms, source} → {output, prompt, view, waitingInput}

POST

/api/disconnect

断开当前会话

POST

/api/clear

清空窗口历史

import json, urllib.request

BASE = "http://127.0.0.1:8199"

def api(path, data=None):
    req = urllib.request.Request(
        BASE + path,
        data=json.dumps(data).encode() if data is not None else None,
        headers={"Content-Type": "application/json"},
        method="POST" if data is not None else "GET",
    )
    return json.loads(urllib.request.urlopen(req, timeout=30).read().decode())

api("/api/connect", {"transport": "telnet", "host": "192.168.1.1",
                     "username": "admin", "password": "***"})
print(api("/api/exec", {"command": "display version", "wait_ms": 8000})["output"])
api("/api/disconnect", {})

想让 LLM Agent 按「先思考 → 命令上屏 → 逐步播报」的规矩干活，见 docs/agent-bridge.md。

多厂商兼容

能力

Huawei VRP

H3C Comware

Cisco IOS

提示符识别

<HOST> / [HOST] / [HOST-GE0/0/1] / [~HOST]

同左

SW1> / SW1# / SW1(config)#

关闭分页

screen-length 0 temporary

同左

terminal length 0

分页标记

---- More ----

同左

--More--

交互确认

[Y/N]: 立即返回

同左

同左

厂商精判

display version

display version

show version

识别顺序：连接 banner 关键字 → display version / show version → 提示符兜底。实测在 FutureMatrix（华为系）设备上不会误判为 H3C。

实战踩过的坑（都已修）

这些是拿真实生产设备磨出来的，写在这里省你几天时间：

  1. 命令首字符被吞 上一条命令停在 ---- More ---- 时，VRP 把新命令的第一个 d 当作「向下翻半屏」的按键。→ execute() 发送前先做 0.15s 残留探测，有输出就完整排干（含自动翻页）。

  2. SSH 必须用 invoke_shell 网络设备不支持 exec 通道，paramiko.exec_command 一律失败。必须 invoke_shell(term='vt100', width=200, height=60) 走交互式 shell。

  3. 主机密钥必须先接受 设备没有稳定指纹，RejectPolicy 会卡在 yes/no。→ AutoAddPolicy。

  4. 华为 display ip pool 的接口名不带空格 display ip pool name Vlanif1 used 报错，正确的是 display ip pool interface Vlanif1 used。

  5. 不可逆密码 + 老固件的 SSH 密码认证可能完全不可用 某些 VRP 版本（实测 V200R020C30）即使 telnet 同密码可登录，SSH 密码认证恒为 User password authentication failed；想改可逆存储 cipher 又被拒（not allowed to use a reversible encryption algorithm）。换客户端（paramiko / asyncssh）、换认证域、重建 ssh user 绑定均无效。→ 这类设备只能走 Telnet / Console，代码无需改。

  6. USB 转串口线要认芯片 PL2303 经典款（VID_067B&PID_2303）必须用 3.x 版驱动，5.x 只支持新芯片（23A3/23B3/23C3），装上去设备管理器直接报错。

  7. Windows 下设备会主动断连 长会话偶尔出现 WinError 64 / 10054，是设备侧行为，重连即可，别去改客户端参数。

目录结构

net-cli-mcp/
├── server.py                  # MCP 服务：会话管理 + 多厂商适配（无拦截）
├── secure_server.py           # 加固版 MCP 入口：白名单 + 审批 + 脱敏 + 审计
├── security.py                # 策略与脱敏的公共实现（两个安全入口共用）
├── secure_console.py          # 加固版控制台入口：重建路由 + 令牌 + 审批
├── selftest.py                # 自测，全绿才算加固生效
├── console/
│   ├── app.py                 # Web 控制台后端（Starlette + SSE）
│   ├── static/index.html      # 前端窗口（单文件，无构建）
│   ├── start-console.bat
│   ├── 启动安全控制台.bat    # 加固版启动：手输审批码，回车=只读
│   └── stop-console.bat
├── docs/
│   ├── agent-bridge.md        # 让 LLM Agent 驱动控制台的规范
│   └── security-hardening.md  # 加固策略、审批码、残余风险
├── requirements.txt
├── mcp-config.example.json
└── LICENSE

安全说明

  • 控制台只绑 127.0.0.1，不对外网开放。

  • Telnet 是明文协议，账号密码在网络上是裸奔的。生产环境请优先 SSH / Console 串口，或把 Telnet 限制在带外管理网。

  • 未加固的默认入口不做权限拦截：server.py 和 console/app.py 会把 AI 给的命令原样下发，把设备交给自动化前请改用 secure_server.py / secure_console.py（见上文）。

  • 加固入口的只读识别是启发式规则，脱敏是正则，都不构成设备侧的授权控制；真正的边界是设备 AAA/RBAC 和只读账号。

  • console/logs/ 里有完整设备回显，可能含敏感信息，已在 .gitignore 中排除。

致谢

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    This server cannot be deployed

    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • network-mcp

      E-Conners-Lab
      A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI assistants with direct access to multi-vendor network devices for tasks like configuration management, health checks, and topology discovery through 35 specialized tools. It enables natural language control over platforms including Cisco, Juniper, and Nokia using SSH, NETCONF, and SNMP protocols.
      12
      MIT

    • NetPilot-MCP

      czgreg
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables large language models to manage network devices (Cisco, Huawei, H3C, Ruijie) via Telnet/SSH, supporting command execution, configuration, and diagnostics.
      15
      MIT

    • NetContext MCP

      hgursel
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to execute SSH commands on network devices using natural language, supporting multiple vendors and authentication methods for automated network management.
      GPL 3.0