内容
gns3-mcp -- 人工智能驱动的网络工程
[](LICENSE)
[](https://www.rust-lang.org)
[](https://modelcontextprotocol.io)
[](#available-tools-25)
[](#quick-start)
**gns3-mcp** 是一个高性能的MCP服务器，使用 **Rust** 编写，提供 REST API v2** 接口给 Claude，使您的AI助手成为一名全面的网络工程师，可以通过自然对话设计、部署和管理复杂的实验室拓扑。
---
## 为什么选择 gns3-mcp？
停止通过图形界面点击来构建实验室。使用 `gns3-mcp`，Claude 可以：
- **设计** 整个拓扑结构，根据文本描述。
- **部署** 和连接节点（思科、Arista、Docker、...）只需几秒- **检查** 和的实时状态。
-** 整个设备生命周期 - 启动、停止和重新配置 - 通过语音或文本。
您和在同一个 GNS3工作：您在图形界面调整，而 Claude 通过对话进行部署和连接。实时、双向。
---
## 亮点
- **超轻量级**：~19 MB Docker 镜像（`distroless/static`，musl 静态二进制文件）。
- **25 个 MCP 工具**：项目、节点、链接、模板、计算服务器的完整 CRUD 操作，以及批量和复合操作。
- **弹性**：5xx 错误自动重试，指数退避（3 次尝试，100/200/400 毫秒），服务器宕机时熔断器。
- **熔断器**：三状态异步熔断器（关闭/打开/半打开）防止 GNS3 宕机时请求风暴。
- **安全设计**：零 OpenSSL/glibc 依赖（rustls），每个输入的 UUID 验证，凭证从不记录，非 root 容器。
- **清洁架构**：3-crate Rust 工作区，严格的依赖反转和基于特性的注入。
- **零摩擦**：stdio 传输 - 原生 Claude Desktop 和 Claude Code 集成，无需额外基础设施。
---
## 架构
```
gns3-mcp/
+-- Cargo.toml # 工作区根目录 + 共享依赖
+-- crates/
| +-- core/ # 类型、特性、错误（零网络依赖）
| +-- gns3-client/ # 实现 Gns3Api 的 HTTP 客户端
| +-- mcp-server/ # MCP 工具，stdio 启动
+-- docs/adr/ # 架构决策记录
+-- .github/workflows/ # CI + Docker 流水线
+-- Dockerfile # 多阶段：Alpine 构建 -> distroless 运行时
```
项目强制执行严格的依赖规则（依赖反转）：
```
mcp-server --> （仅特性）
mcp-server -.-> gns3-client （仅在 main.rs 中注入）
gns3-client --> core （类型 + Gns3Api 特性）
core --> nothing （serde, thiserror, uuid）
```
> **关键见解**：`mcp-server` 对 HTTP 或 reqwest 零知识。它仅通过 `core` 中定义的 `Gns3Api` 特性进行交互，使每个工具都可以使用模拟进行完全单元测试 - 不需要 GNS3 服务器。
---
## 快速入门
### 先决条件
- GNS3 服务器 2.2.x+通过 HTTP 访问
- Rust 1.75+ **或** Docker
### 选项 1：Docker（推荐）
```bash
docker build -t gns3-mcp:latest .
docker run --rm -i \
-e GNS3_URL=http://localhost:3080 \
--network host \
gns3-mcp:latest
```
> **注意**：需要 `--network host` 以便容器可以访问 `localhost` 上的 GNS3。在 macOS/Windows Docker Desktop 上，请改为使用 `-e GNS3_URL=http://host.docker.internal:3080`。
### 选项 2：从源代码构建
```bash
cargo build --release
GNS3_URL=http://localhost:3080 ./target/release/gns3-mcp
```
---
## Claude Desktop / 配置
在您的配置文件（`claude_desktop_config.json` 或 `.claude/settings.json`）中添加：
```json
{
"mcpServers": {
gns3": {
command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "GNS3_URL",
", "GNS3_USER",
"-e", "GNS3_PASSWORD",
"--network", "host",
"3-mcp:latest"
],
"env": {
GNS3_URL": "http://localhost:"
}
}
}
}
```
凭证使用 Docker 传参（`-e VAR` 无 `=value`）。在您的 shell 或 `.env` 文件中定义它们 - 永远不要在 JSON 配置中。
### 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
|NS3_URL` | 是 | `http://127.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 在项目画布上 |
### 快照和导出
| 工具 | 功能 |
|---|---|
| `gns3_export_project` | 将项目导出为可移植存档 |
| `gns3_snapshot_project` | 创建命名快照以回滚 |
### 典型
```
1. gns3_get_version -- 验证连接性
2ns3_create_project -- 或 gns3_list用一个
3ns3_open_project 锁节点和链接操作
4. gns3 -- 发现
5. g_create_node -- 每个设备重复
6.3_create_link -- 每个电缆重复
7ns3_start_all_nodes -- 一次启动所有8. gns_topology -- 拓扑
```
---
## 弹性
- 5xx**：指数退避（100 毫秒，200 毫秒，400 毫秒），最多 34xx 和网络错误立即失败 - 不会处理错误的请求。
熔断器**：5 次连续失败停止调用 GNS30 秒后使用探测 - 在宕保护服务器。
-配置超时**：`GNS3_TIMEOUT_SECS变量，默认为 。
- **可操作的错误**：返回给 Claude 的每个错误都解释了失败的原因并建议下一步。
---
## 安全
| 属性 | 详情 |
|---|---|
凭证** | 仅限环境变量 - 永远，永远不会在错误消息中显示，永远不会 可见 |
| **输入验证** | 在进行任何 API 调用之前验证每个 UUID **容器** | `distroless/static:nonroot` - 没有 shell，没有特权用户 |
| **TLS**纯 Rust `rustls 没有 OpenSSL，没有 依赖 |
| **二进制文件** | 静态 musl - 零 |
---
##```bash
cargo check --workspace # 类型检查
--workspace # 61+ 个单元测试，不需要 GNS3
cargo clippy --workspace -- -D warnings # lint警告策略）
cargo fmt --check # 格式检查
```
CI 通过 GitHub Actions 在每次推送和拉取请求时自动运行。
---
## 兼容性
gns3-mcp 使用标准的 **JSON-RPC over stdio** - 开放的 MCP 协议。任何实现 MCP 的客户端都可以使用它，而不仅仅是 Claude。
| 客户端 | 状态 | 备注 |
|---|---|---|
| **Claude Desktop / Code** | 原生 | stdio 开箱即用 |
| **OpenAI / ChatGPT** | 支持 | MCP 支持于 2025 年 3 月宣布 |
| **Cursor** | 原生 | 内置 MCP 客户端 |
| **Windsurf** | 原生 | 内置 MCP 客户端 |
| **Continue.dev** | 原生 | 将 MCP 桥接到任何 LLM 后端（Ollama，llama.cpp 等） |
| **LM Studio** | 通过包装器 | 需要 MCP 客户端层（例如 Python `mcp` SDK） |
| **自定义代理** | 是 | 任何可以生成子进程并向 stdin 写入 JSON-RPC 的代码 |
> **模型能力说明**：体验质量取决于 LLM 正确理解工具描述和排序调用的能力（例如 `open_project` 之前为 `create_node`）。大型模型（70B+，Claude，GPT-4）很好地处理了这一点。较小的本地模型（7-13B）可能难以进行多步骤工具协调。
---
## 架构决策
设计原理记录在 `docs/adr/` 中：
| ADR | 决策 |
|---|---|
| 0001 | **stdio 而非 SSE** - 原生 Claude Desktop 支持，零基础设施 |
| 0002 | **Alpine + distroless** - musl 静态二进制文件，最终镜像约 19 MB |
| 0003 | **rustls 而非 OpenSSL** - musl 交叉编译无 glibc 摩擦 |
| 0004 | **core 中的 Gns3Api 特性** - 将服务器与客户端解耦，实现模拟测试 |
| 0005 | **熔断器** - 服务器宕机时快速失败，自动恢复 |
| 0006 | **#[non_exhaustive] 错误** - semver 安全错误枚举演化 |
---
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发设置和指南。
## 安全
参见 [SECURITY.md](SECURITY.md) 了解我们的漏洞披露政策。
---
## 许可证
MIT - 参见 [LICENSE](LICENSE)
