pnetlab-mcp-server

一个 MCP 服务器,让 Claude(以及其他 LLM Agent)可以通过自然语言程序化控制 PNETLab v6 网络实验环境 -- 创建拓扑、 添加节点、连线、推送配置、启动节点并读取状态、驱动设备控制台、注入链路故障。

它复刻了 axiom-works-ai/eveng-mcp-server 的工具集,但对接的是 PNETLab v6 的会话级 API,而不是 v6 已经移除的经典 EVE-NG API。

⚠️ 生成与测试说明
本项目代码完全由 AI 生成。基础功能已经过实际测试,但未做全面覆盖测试。建议在正式使用前让 Agent 自行针对你的 PNETLab 环境跑一轮验证。

为什么需要它

PNETLab v6(6.0.0+)是一次 Laravel 重写,保留了旧 EVE-NG 引擎(仍在 /api/ 下),但是:

• 删除了经典登录(/api/auth/login)、/api/status、/api/labs/、 /api/folders/、/api/users/。

• 把实验操作迁移到会话级 API:/api/labs/session/*。

• 替换了登录方式,改为 Laravel 端点:POST /store/public/auth/login/login。

所以 eveng-mcp-server(走经典 API)在 v6 上无法工作。本服务器是针对 PNETLab 6.0.0-100 逆向工程并实际验证过的。

Related MCP server: nornir-mcp-server

安装

pip install -e .

安装后提供 pnetlab-mcp-server 命令。

配置

设置环境变量(服务器在第一次调用工具时才会懒加载登录):

为什么要专用工作账号? v6 每个用户账号只能有一个活跃的实验会话。如果 Agent 和你的浏览器都用 admin,open_lab 会报 20039 "sandbox already exists"。给 Agent 一个独立账号(例如 mcp,admin 角色),你的浏览器就自由了。

在浏览器里实时查看。 当设置了 PNETLAB_VIEWER_* 时,open_lab 会自动把 查看账号加入 Agent 的实验会话 -- 于是两者共享同一个实时拓扑。Agent 打开实验 后,只要用查看账号登录 PNETLab 网页 UI 并打开该实验(或访问 /legacy/topology):你就能看到 Agent 的拓扑,刷新即可看到它的改动。 join_viewer 用于在你先打开了浏览器时重新加入;close_lab 也会让查看账号退出。

Claude Code(.claude.json)

{
  "mcpServers": {
    "pnetlab": {
      "command": "pnetlab-mcp-server",
      "env": {
        "PNETLAB_HOST": "http://192.168.231.128",
        "PNETLAB_USERNAME": "mcp",
        "PNETLAB_PASSWORD": "pnet",
        "PNETLAB_VIEWER_USERNAME": "admin",
        "PNETLAB_VIEWER_PASSWORD": "pnet"
      }
    }
  }
}

添加后重启 Claude Code。

工具

列表与模板

实验会话

节点

链路与故障注入

控制台交互(免手写 telnet)

重要注意事项(v6 专属)

1. 每个账号一个会话。 v6 每个账号只能有一个活跃实验会话。Agent 必须用 专用账号(例如 mcp),不能用你浏览时用的账号。配置 PNETLAB_VIEWER_*, open_lab 会自动把你的浏览账号加入 Agent 的会话 -- 两者共享同一个实时拓扑 (见上文"配置")。

2. 所有 /api/labs/session/* 调用都用 JSON body。 表单编码的 body 会被 静默丢弃,表现为 40000 "missing required fields"。

3. open_lab 的 path 没有前导斜杠 -- 是 "2pc_1sw.unl",不是 "/2pc_1sw.unl"。

4. add_node 默认自动套用模板。 建节点时会自动拉取模板自带默认值 (image/ram/cpu/qemu_arch/qemu_nic/qemu_options/qemu_version/console/config_script) 并填入,与 GUI 建的节点完全一致 -- 所以 add_node("qemu","mikrotik","R1") 就能直接建出可启动、可连控制台的节点,通常无需先 list_images。显式传入的 字段覆盖模板默认;template_defaults=false 可关闭。想换镜像时再用 list_images 查可用项,传 image=... 覆盖。

5. console 默认 telnet。 PNETLab 通过控制台端口是否在监听来判断节点 "运行中"(状态 2)。console 为空时不会起 qemu_wrapper_telnet 转发器, 端口不监听,于是状态恒为 0、控制台也连不上 -- 看起来像"启动即崩",实际 节点在跑。add_node 已默认 console="telnet";如需 ssh/winbox/http 等 显式传入即可。

6. open_lab 会在服务器上创建/复用一个沙盒文件(labs<name>.unl);沙盒在 首次打开时为空。close_lab 释放会话绑定但保留沙盒文件(重新打开没问题)。

7. 删除节点前必须先 stop_node。

8. 不带 id 的 start_node() / stop_node() 会遍历实验的节点 id(API 的 null-id "全部" 路径不可靠)。

9. 链路质量/状态在接口层。 v6 的 network 不带 quality 字段;丢包/延迟/ suspend 都是接口级。本服务器的链路工具会自动找到链路两端的接口并下发。 仅对运行中节点生效(数据存库 + 实时下发)。

10. 控制台会话复用。 一个 PNETLab 控制台端口同时只服务一个 telnet 客户端, run_command/console_send/console_read 按节点复用会话;用完调 console_close。RouterOS 默认 admin/空密码,可在 run_command 里传 username/password 覆盖。

架构

LLM agent  ──MCP/stdio──►  pnetlab-mcp-server  ──HTTP/JSON──►  PNETLab v6
                              (本仓库)                            /store/public/auth/login/login  (登录)
                                                                  /api/labs/session/*             (实验操作)
                                                                  /api/list/templates|networks    (列表)
                                                                  /api/labs/session/interfaces/*  (链路质量/状态)
                                                                  telnet <host>:<console port>    (控制台)

client.py 是经过验证的 v6 API 客户端(含自实现 telnet 控制台,telnetlib 在 Python 3.13+ 已移除);server.py 把它封装为 MCP 工具。