Skip to main content

如何使用 MCP 服务

MCP（Model Context Protocol）是一种开放标准，用于让 AI 助手与外部工具和服务进行安全交互。GNS3 Server 提供了标准的 MCP 接口，允许 AI 助手（如 Claude Code）通过 SSE（Server-Sent Events）传输协议与 GNS3 进行交互。

通过 MCP 服务，您可以直接使用自然语言命令 AI 助手来管理 GNS3 项目、节点、链路、模板和计算节点，无需手动操作 GNS3 GUI/Web UI。

除使用现成客户端外，您还可以基于 MCP 构建自定义 AI Agent，或将其集成到现有 AI 工作流中，实现自动化测试验证。

前置条件​

  • GNS3 服务端已启动运行
  • 拥有 GNS3 的用户账号（默认用户名/密码：admin/admin）

服务端点​

路径方法说明
/v3/mcp/GETMCP 服务元数据
/v3/mcp/transport/sseGETSSE 流（MCP 连接入口）
/v3/mcp/transport/messages/POSTJSON-RPC 消息

认证方式​

MCP 服务支持两种凭证方式：JWT Token（24小时有效期）或 API Key（永久有效，可吊销）。

创建 API Key（推荐）​

  • 如下图所示，登录服务器后，点击右侧三个点按钮，然后选择 API Key 选项。

API Key 菜单选项

  • 在弹出的 API Keys 对话框中，点击 Create your first API key 按钮。

创建第一个 API Key

  • 为即将创建的 API Key 输入一个名称，然后点击 Create 按钮。

输入 API Key 名称

  • 后端创建完成后，会显示 API Key Created 对话框，复制并保存此 Key。

API Key 创建成功

warning

此 API Key 只显示一次，复制保存后，将不会再次显示。请立即妥善保存。

  • 创建完成后，列表中将显示该 Key。

API Key 列表

  • 在 Actions 中，可以点击 Revoke 按钮吊销某个 Key。

吊销 API Key

  • 吊销后，可以点击 Restore 恢复或 Delete 永久删除。

吊销后状态

  • 点击Restore恢复

恢复确认对话框

  • 点击Delete永久删除

删除确认对话框

快速开始​

在 Claude Code 中使用​

# 添加 MCP 服务器
claude mcp add --transport sse My_GNS3_Server \
  http://localhost:3080/v3/mcp/transport/sse \
  -H "Authorization: Bearer $API_KEY"

参数说明：

  • --transport sse — 使用 SSE（Server-Sent Events）传输协议，MCP 的标准传输方式，支持远程连接
  • My_GNS3_Server — 自定义的 MCP 服务器名称，可任意命名，用于在 Claude Code 中标识该服务器
  • http://localhost:3080/v3/mcp/transport/sse — GNS3 服务端的 MCP SSE 端点地址，localhost 为 GNS3 服务端地址，3080 为默认端口
  • -H "Authorization: Bearer $API_KEY" — 携带 API Key 的认证请求头，$API_KEY 替换为上一步获取的 API Key 值

添加完成后，在 Claude Code 中即可通过自然语言管理 GNS3，例如：

  • "列出所有 GNS3 项目"
  • "创建一个名为'OSPF 实验'的新项目"
  • "在项目中添加一个 Cisco 路由器"
  • "启动节点并检查状态"

可用工具​

MCP 服务提供 82 个工具，分为 12 大类：

项目（15 个）​

工具说明必需参数
project_list列出所有项目无
project_get获取项目详情project_id
project_create创建项目name
project_delete删除项目project_id
project_open打开已关闭的项目project_id
project_close关闭已打开的项目project_id
project_stats获取项目统计信息project_id
project_update更新项目属性project_id
project_duplicate复制项目project_id, name
project_readme_get获取项目说明内容project_id
project_readme_update更新项目说明project_id, content_markdown
project_lock锁定项目（防止编辑）project_id
project_unlock解锁项目project_id
project_load从路径加载项目path
project_locked检查项目是否已锁定project_id
note

调用 project_unlock 解锁后，查询项目状态可能仍然显示 locked=true，这是状态同步的正常延迟。

节点（22 个）​

工具说明必需参数
node_list列出项目中所有节点（fields 可过滤列，如 ["name","status"]）project_id
node_get获取节点详情（fields 可过滤列）project_id, node_id
node_create创建节点——单个用 template_id，批量用 nodes 数组。批量时顶层 template_id 作为默认值，各条目可用 name 自定义名称；坐标原点为画布中心，X 向右为正、Y 向下为正project_id, template_id
node_delete删除节点project_id, node_id
node_update更新节点属性project_id, node_id
node_start启动节点——支持 node_id 或 node_ids 数组project_id, node_id
node_stop停止节点——支持 node_id 或 node_ids 数组project_id, node_id
node_reload重启节点——支持 node_id 或 node_ids 数组project_id, node_id
node_suspend挂起节点——支持 node_id 或 node_ids 数组project_id, node_id
node_console获取控制台 WebSocket 地址project_id, node_id
node_file_list列出节点目录中的文件project_id, node_id
node_file_get读取文件（支持偏移/限制）project_id, node_id, path
node_file_write写入文件project_id, node_id, path, content
node_file_delete删除文件project_id, node_id, path
node_start_all启动项目中所有节点project_id
node_stop_all停止项目中所有节点project_id
node_suspend_all挂起项目中所有节点project_id
node_reload_all重启项目中所有节点project_id
node_duplicate复制节点project_id, node_id
node_isolate隔离节点（挂起其链路）project_id, node_id
node_unisolate取消隔离节点（恢复链路）project_id, node_id
node_links列出连接到节点的所有链路project_id, node_id
note

node_console 返回的 WebSocket 地址需要使用 websocat 工具连接，请确保在运行 Claude Code 的系统中已安装该工具。安装方法：cargo install websocat（需 Rust 环境）或从 GitHub Releases 下载预编译二进制。

node_console 返回的 WebSocket 地址内含一个短期 JWT（有效期 10 分钟），过期后需重新调用该工具获取新地址。该地址与协议无关——对 telnet、ssh、vnc 三种控制台类型通用。WebSocket 仅在客户端与计算节点之间透传原始字节流，协议协商（例如 SSH 密钥交换）发生在计算节点侧。

warning

node_suspend 的行为因节点类型而异：

  • Docker / Dynamips / QEMU：完全支持挂起 — 状态变为 suspended
  • VPCS / IOU：不支持挂起 — 返回 405（被 controller 吞掉，状态仍为 started）
  • Cloud / NAT / Ethernet switch：无独立进程可挂起 — 仅标记状态，无实际效果 使用挂起前请确认节点类型，并通过 status 字段验证实际操作是否生效。

链路（9 个）​

工具说明必需参数
link_list列出项目中所有链路project_id
link_get获取链路详情project_id, link_id
link_create创建链路——单个用 nodes，批量用 links 数组。节点支持紧凑格式 [id, ad, pt, id, ad, pt]（即 node_id、adapter_number、port_number）project_id, nodes
link_delete删除链路——支持 link_id 或 link_ids 数组project_id, link_id/link_ids
link_update更新链路（挂起、过滤）project_id, link_id
link_reset重置链路（删除后重建）——支持 link_id 或 link_ids 数组project_id, link_id/link_ids
link_capture_start开始抓包——支持 link_id 或 link_ids 数组project_id, link_id/link_ids
link_capture_stop停止抓包——支持 link_id 或 link_ids 数组project_id, link_id/link_ids
link_capture_download获取 PCAP 下载地址——支持 link_id 或 link_ids 数组project_id, link_id/link_ids
note

link_reset 不会清除已有的 filter 设置——仅重建 UDP 连接。节点连接和过滤规则保持不变。

模板（5 个）​

工具说明必需参数
template_list列出所有模板（fields 可过滤列）无
template_get获取模板详情template_id 或 name
template_create创建模板（Docker 需要 image）name, template_type
template_update更新模板template_id 或 name
template_delete删除模板template_id 或 name

计算节点（3 个）​

工具说明必需参数
compute_list列出所有注册的远程计算节点无
compute_get获取计算节点详情compute_id
compute_images列出计算节点上的仿真器镜像compute_id, emulator
note

compute_images 专用于远程计算节点。要查询本地计算节点的镜像，请使用 image_list。

快照（4 个）​

工具说明必需参数
snapshot_list列出快照project_id
snapshot_create创建快照project_id, name
snapshot_delete删除快照project_id, snapshot_id
snapshot_restore恢复快照project_id, snapshot_id

绘图（5 个）​

工具说明必需参数
drawing_list列出画布上的绘图project_id
drawing_get获取绘图详情project_id, drawing_id
drawing_create创建绘图（SVG 标签/形状/图片）project_id, svg
drawing_update更新绘图（位置、旋转、SVG）project_id, drawing_id
drawing_delete删除绘图project_id, drawing_id
warning

GNS3 的 SVG 渲染器与标准 SVG 规范存在以下差异：

  • <rect> 必须使用有效的颜色填充值（如 fill="#FF0000"），否则无法显示。不支持 fill="none"。
  • <ellipse> 无此限制。
  • <path> 的 Z（闭合）命令可能无法正常生效。 创建自定义绘图 SVG 时请注意这些渲染差异。

符号（6 个）​

工具说明必需参数
symbol_list列出所有符号无
symbol_get获取符号下载地址symbol_id
symbol_dimensions获取符号尺寸symbol_id
symbol_defaults获取默认符号映射无
symbol_upload上传自定义符号（SVG）symbol_id, svg_content
symbol_delete删除自定义符号symbol_id

应用模板（3 个）​

工具说明必需参数
appliance_list列出模板库中的应用模板（fields 可过滤，如 ["name","category"]）无
appliance_get获取应用模板详情appliance_id
appliance_install从应用模板创建模板appliance_id

镜像（5 个）​

工具说明必需参数
image_list列出所有镜像无
image_get获取镜像详情image_id
image_delete删除镜像image_id
image_prune清理未被任何模板引用的镜像无
image_install根据校验和从已上传镜像自动创建模板无
warning

使用 image_install 前，需要先将镜像文件手动放到服务端的 ~/GNS3/images/ 目录下。该工具不会自动下载镜像——它仅通过校验和匹配从已有镜像文件创建模板。

服务器（2 个）​

工具说明必需参数
server_version获取 GNS3 服务端版本无
server_statistics获取服务器统计信息（计算节点、项目、节点数）无

设备配置（3 个）​

工具说明必需参数
device_config_send通过控制台推送配置命令到设备（Nornir + Netmiko）。支持 Jinja2 template + varsproject_id, device_name, config_commands
device_show_run在设备上执行只读 show 命令。支持 Jinja2 template + varsproject_id, device_name, commands
vpcs_config_set配置 VPCS 设备（IP、网关等）project_id, device_name, ip, netmask, gateway
note

必须先启动节点，才能对设备进行配置。设备类型会从节点的 device_type:<type> 标签自动识别。

设备配置工作流​

Jinja2 模板模式​

device_config_send 和 device_show_run 都支持可选的 template 参数。提供时，每个设备的 vars 字典会与模板渲染生成命令。相同 device_name 的条目会合并到同一个会话。

# 直接命令（单个/批量）
device_config_send(project_id, device_configs=[
    {"device_name": "R1", "config_commands": ["int lo0", "ip add 1.1.1.1 255.255.255.255"]},
])

# Jinja2 模板（批量时可减少 token 消耗）
device_config_send(project_id,
    template="interface lo{{ n }}\nip address {{ ip }} 255.255.255.255",
    device_configs=[
        {"device_name": "R1", "vars": {"n": 0, "ip": "1.1.1.1"}},
        {"device_name": "R2", "vars": {"n": 0, "ip": "2.2.2.2"}},
    ])

最佳实践​

  • 批量时优先用模板而非直接命令——当 ≥2 个节点配置结构相同、仅值不同时，用 template + vars 替代每个节点写 config_commands，可减少 token 消耗和抄写错误。
  • 不要只看 status: success——它只表示命令进入了配置模式。IOS 错误（% Invalid input、% overlaps、% Incomplete command）藏在 output 文本里，务必扫描 % 开头的行。
  • 先小批量验证再全量——先在 1-2 台设备上测试 template + vars，确认渲染和语法正确，再扩展到所有节点。

通过文件操作备份配置​

IOU 和 Dynamips 节点在执行 write memory 后，启动配置会保存为节点目录下的纯文本文件（startup-config.cfg）。可通过 node_file_get / node_file_write 备份和恢复。

# 在设备上保存配置
device_show_run(project_id, device_configs=[
    {"device_name": "R1", "commands": ["write memory"]},
])
# 备份
config = node_file_get(project_id, node_id, "startup-config.cfg")
# 配置损坏时恢复
node_file_write(project_id, node_id, "startup-config.cfg", config)
node_reload(project_id, node_id)

测试报告​

82 个工具的完整测试结果保存在 gns3-api-mcp-test 仓库中：

演示视频​

📺 观看中文演示视频

架构概览​

下图展示客户端从连接认证到工具发现与调用的完整交互流程：

传输安全配置​

GNS3 Server 的 MCP 服务默认允许所有主机连接，与 GNS3 server 监听 0.0.0.0（所有网络接口）的策略一致。

如需限制访问来源，可在 gns3_server.conf 中启用 DNS 反绑定保护。mcp_allowed_hosts 填写客户端访问 GNS3 server 时使用的地址，而非客户端自身的地址：

[Server]

; 启用 MCP 传输安全保护（默认 False）
mcp_enable_dns_rebinding_protection = True

; 允许客户端访问的 GNS3 server 地址列表（"host:port" 格式）
; 例如 GNS3 server IP 为 192.168.1.3，则填写 192.168.1.3:*
mcp_allowed_hosts = 127.0.0.1:*,localhost:*,192.168.1.3:*

; 允许的来源列表（CORS Origin）
mcp_allowed_origins = http://127.0.0.1:*,http://localhost:*,http://192.168.1.3:*
tip

默认配置下所有主机均可连接，适合大多数场景。仅在需要严格限制访问来源时启用保护。

内部实现机制​

MCP 服务基于 FastMCP（Anthropic MCP SDK）实现，以 Starlette 子应用挂载在 /v3/mcp/transport 下；工具处理器通过 Gns3Connector 调用 GNS3 自身的 REST API，使 MCP 层与业务解耦。JWT Token 经 GNS3 既有 auth_service 校验，并通过 contextvars.ContextVar 在 asyncio.to_thread（Python ≥ 3.9）的工作线程中传递。

node_console 返回的 WebSocket 地址由服务端 _server_url() 构造，其 host 解析规则如下（影响远程连接时的可达地址）：

Server.host 取值URL 中解析出的 host
具体 IP 或主机名（如 192.168.1.3）原样使用
0.0.0.0（IPv4 任意，默认）经默认路由网卡 IP 探测得到
::（IPv6 任意）经默认路由网卡 IP 探测得到
探测失败回退到 127.0.0.1

当 Server.host 为 0.0.0.0 时，服务端通过向 8.8.8.8:80 发起 UDP socket 连接来探测默认路由网卡的 IP（不会真正发送数据），从而保证返回的地址可达：

websocat ws://192.168.1.3:3080/v3/projects/{project_id}/nodes/{node_id}/console/ws?token=<jwt>

常见问题​

MCP 和 GNS3 Copilot 有什么区别？​

  • GNS3 Copilot（AI 助手）：内置于 GNS3 GUI 的 AI 功能，通过 LLM 实现拓扑管理、故障诊断和自动化配置
  • MCP 服务：提供标准化的 MCP 协议接口，允许外部 AI 客户端（如 Claude Code）以统一方式调用 GNS3 功能

两者可以配合使用：MCP 服务于工具调用场景，AI 助手服务于 GUI 内交互式使用场景。

是否支持远程连接？​

支持。将 localhost 替换为 GNS3 服务端的实际 IP 地址或域名即可远程连接。注意确保网络可达且服务端端口（默认 3080，GNS3 VM默认80）已开放。

功能贡献者​

MCP 服务功能由 YueGuobin 开发和贡献。

License​

本文档采用 CC BY-NC-ND 4.0 许可协议（署名-非商业性使用-禁止演绎）。 作者: 岳国宾