使用说明

gns3 mcp——基于人工智能的网络工程

gns3 mcp 是用编写的高性能MCP服务器锈这暴露了 GNS3 REST API v2 Claude将你的人工智能助手变成一名成熟的网络工程师——通过自然对话设计、部署和管理复杂的实验室拓扑。

为什么选择gns3 mcp？

停止点击GUI来构建实验室。随着 gns3-mcp，克劳德可以：

设计从文本描述中提取整个拓扑结构。
部署以及有线节点（思科、Arista、Docker、VPCS……）。
检查并记录你实验室的实时状态。
操作通过语音或文本完成整个设备生命周期（启动、停止和重新配置）。

您和Claude同时处理同一个GNS3项目：当Claude从对话中部署和连接时，您在GUI中进行调整。实时、双向。

亮点

超轻：~19 MB Docker镜像(distroless/static，musl静态二进制）。
25个MCP工具：用于项目、节点、链接、模板、计算服务器以及批处理和复合操作的完整CRUD。
坚韧的：对5xx错误进行指数回退的自动重试（3次尝试，100/200/400ms），服务器中断的断路器。
断路器：三态异步断路器（闭合/打开/半打开）可在GNS3关闭时防止请求风暴。
设计安全：零OpenSSL/glibc依赖（rustls），对每个输入进行UUID验证，从不记录凭据，非根容器。
整洁架构：3格Rust工作空间，具有严格的依赖反转和基于特征的注入。
零摩擦：stdio传输——原生Claude Desktop和Claude Code集成，无需额外的基础设施。

建筑

gns3-mcp/
+-- Cargo.toml              # workspace root + shared deps
+-- crates/
|   +-- core/               # types, traits, errors (zero network deps)
|   +-- gns3-client/        # HTTP client implementing Gns3Api
|   +-- mcp-server/         # MCP tools, stdio bootstrap
+-- docs/adr/               # Architecture Decision Records
+-- .github/workflows/      # CI + Docker pipelines
+-- Dockerfile              # multistage: Alpine build -> distroless runtime

该项目强制执行严格的依赖关系规则（依赖关系反转）：

mcp-server  -->  core          (traits only)
mcp-server  -.-> gns3-client   (injected in main.rs only)
gns3-client -->  core          (types + Gns3Api trait)
core        -->  nothing       (serde, thiserror, uuid)

关键洞察: mcp-server 对HTTP或reqwest一无所知。它只通过 Gns3Api 特征定义于 core，使每个工具都可以通过模拟进行完全的单元测试——不需要GNS3服务器。

快速开始

先决条件

GNS3服务器2.2.x+，正在运行并可通过HTTP访问
锈蚀1.75+ 或码头工人

选项1:Docker（推荐）

docker build -t gns3-mcp:latest .

docker run --rm -i \
  -e GNS3_URL=http://localhost:3080 \
  --network host \
  gns3-mcp:latest

备注: --network host 是必需的，因此容器可以在以下时间到达GNS3 localhost。在macOS/Windows Docker桌面上，使用 -e GNS3_URL=http://host.docker.internal:3080 相反。

选项2：从源代码构建

cargo build --release
GNS3_URL=http://localhost:3080 ./target/release/gns3-mcp

克劳德桌面/Claude代码配置

添加到配置文件(claude_desktop_config.json 或 .claude/settings.json):

{
  "mcpServers": {
    "gns3": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GNS3_URL",
        "-e", "GNS3_USER",
        "-e", "GNS3_PASSWORD",
        "--network", "host",
        "gns3-mcp:latest"
      ],
      "env": {
        "GNS3_URL": "http://localhost:3080"
      }
    }
  }
}

凭据使用Docker传递(-e VAR 没有 =value).在shell中定义它们或 .env file——从不在JSON配置中。

环境变量

变量	必填	默认	描述
`GNS3_URL`	是的	`http://127.0.0.1:3080`	GNS3服务器基本URL
`GNS3_USER`	否	--	基本身份验证用户名
`GNS3_PASSWORD`	否	--	基本身份验证密码
`GNS3_TIMEOUT_SECS`	没有	`30`	HTTP请求超时（秒）
`RUST_LOG`	没有	`info`	日志级别（跟踪、调试、信息、警告、错误）

可用工具（25）

项目

工具	它做什么
`gns3_get_version`	验证GNS3服务器连接和版本
`gns3_list_projects`	列出所有具有状态的项目
`gns3_create_project`	创建并打开一个新项目
`gns3_open_project`	打开现有项目（节点/链接操作前需要）
`gns3_close_project`	关闭项目，释放资源
`gns3_delete_project`	永久删除项目
`gns3_get_topology`	完整快照：一次调用中的所有节点+所有链接

节点

工具	它做什么
`gns3_list_templates`	发现可用的设备（路由器、交换机等）
`gns3_create_node`	将模板中的节点部署到画布上
`gns3_list_nodes`	列出具有状态、类型和控制台端口的节点
`gns3_start_node`	启动单个节点
`gns3_stop_node`	关闭单个节点
`gns3_delete_node`	从项目中删除节点
`gns3_update_node`	更新节点的名称、计算或属性
`gns3_configure_switch`	配置交换机端口映射（VLAN、中继线）
`gns3_start_all_nodes`	一次启动项目中的每个节点
`gns3_stop_all_nodes`	立即关闭项目中的每个节点

链接

工具	它做什么
`gns3_create_link`	将两个节点接口连接在一起
`gns3_list_links`	列出项目中的所有连接
`gns3_delete_link`	删除连接

基础设施

工具	它做什么
`gns3_list_computes`	列出具有CPU/内存使用情况的计算服务器

模板

工具	它做什么
`gns3_update_template`	更新模板属性（RAM、接口、图像）

图纸

工具	它做什么
`gns3_add_drawing`	将SVG图形添加到项目画布

快照和导出

工具	它做什么
`gns3_export_project`	将项目导出为可移植存档
`gns3_snapshot_project`	创建用于回滚的命名快照

典型工作流程

1. gns3_get_version        -- verify connectivity
2. gns3_create_project     -- or gns3_list_projects to reuse one
3. gns3_open_project       -- unlock node and link operations
4. gns3_list_templates     -- discover available appliances
5. gns3_create_node        -- repeat for each device
6. gns3_create_link        -- repeat for each cable
7. gns3_start_all_nodes    -- boot everything at once
8. gns3_get_topology       -- review the live topology

韧性

请在5xx重试：指数退避（100ms、200ms、400ms），最多3次重试。4xx和网络错误会立即失败，不会在错误请求上浪费时间。
断路器：连续5次失败后自动停止调用GNS3。使用探测请求在30秒后恢复--在停机期间保护服务器。
可配置超时: GNS3_TIMEOUT_SECS env-var，默认30秒。
可操作的错误：返回给克劳德的每个错误都解释了失败的原因，并建议了下一步。

安全

物业	详细信息
凭证	仅环境变量——从未记录，从未出现在错误消息中，从未对MCP可见
输入验证	Claude的每个UUID都在任何API调用之前进行验证
容器	`distroless/static:nonroot` --无shell、无包管理器、无特权用户
传输层安全	纯锈 `rustls` --无OpenSSL，无glibc依赖
二进制	静态链接的musl——零动态依赖

发展

cargo check --workspace                    # type-check
cargo test --workspace                     # 61+ unit tests, no GNS3 needed
cargo clippy --workspace -- -D warnings    # lint (zero warnings policy)
cargo fmt --check                          # format check

CI通过GitHub Actions在每个推送和拉取请求上自动运行。

兼容性

gns3 mcp标准语音 基于stdio的JSON-RPC --开放式MCP协议。任何实现MCP的客户端都可以使用它，而不仅仅是Claude。

客户	状态	备注
克劳德桌面/代码	原生	stdio支持开箱即用
OpenAI/ChatGPT	支持	MCP支持于2025年3月宣布
光标	原生	内置MCP客户端
帆板运动	原生	内置MCP客户端
Continue.dev	原生	将MCP连接到任何LLM后端（Ollama、llama.cpp等）
LM 工作室	通过包装器	需要MCP客户端层（例如Python `mcp` SDK）
自定义代理	是	任何可以生成子进程并将JSON-RPC写入stdin的代码

关于型号性能的说明：体验的质量取决于LLM正确理解工具描述和序列调用的能力（例如。 open_project 之前 create_node).大型型号（70B+、Claude、GPT-4）很好地处理了这一点。较小的本地模型（7-13B）可能难以进行多步骤工具编排。

架构决策

设计原理记录在 docs/adr/:

ADR	决定
0001	SSE上的stdio --原生Claude桌面支持，零基础设施
0002	Alpine+无发行版 --musl静态二进制，~19 MB最终图像
0003	OpenSSL上的Rusts --musl交叉编译没有glibc摩擦
0004	核心Gns3Api性状 --将服务器与客户端解耦，启用模拟测试
0005	断路器 --服务器停机时快速故障，自动恢复
0006	#[非详尽]错误 --semver安全错误枚举演化

贡献

看贡献.md 用于开发设置和指南。

安全

看安全.md 我们的漏洞披露政策。

许可证

麻省理工学院——见许可证

使用说明

gns3 mcp——基于人工智能的网络工程

为什么选择gns3 mcp？

亮点

建筑

快速开始

先决条件

选项1:Docker（推荐）

选项2：从源代码构建

克劳德桌面/Claude代码配置

环境变量

可用工具（25）

项目

节点

链接

基础设施

模板

图纸

快照和导出

典型工作流程

韧性

安全

发展

兼容性

架构决策

贡献

安全

许可证

相关 MCP

DuckDuckGo 搜索 MCP 服务器

图表生成MCP服务器

AI开发助手

必应中文搜索MCP服务器

PostgreSQL管理服务器

网页内容获取工具