MCP Gns3

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

    ](#quick-start)

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配置中。

环境变量

______________________________________________________________________

可用工具（25）

项目

节点

链接

基础设施

模板

图纸

快照和导出

典型工作流程

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秒。
• 可操作的错误：返回给克劳德的每个错误都解释了失败的原因，并建议了下一步。

______________________________________________________________________

安全

______________________________________________________________________

发展

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。

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

______________________________________________________________________

架构决策

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

______________________________________________________________________

贡献

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

安全

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

______________________________________________________________________

许可证

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