使用说明

GNS3 MCP服务器

GNS3网络实验室自动化的模型上下文协议（MCP）服务器。通过Claude Desktop或任何兼容MCP的客户端控制GNS3项目、节点和设备控制台。

版本: 0.49.0

特性

15工具：CRUD风格的GNS3自动化（v0.47.0:32个工具的53%整合）
25资源：只读数据访问（项目、节点、链接、会话、拓扑报告）
CRUD模式：整合工具 action 参数(project(action="open"), node(action="create")等等）
批量操作：控制台和SSH操作使用仅批处理的API进行原子执行
通配符支持：节点操作支持模式(*, Router*, R[123]，JSON数组）
项目管理：创建、打开、关闭GNS3项目
节点控制：使用通配符模式和并行执行启动/停止/重启节点
控制台访问：具有模式匹配和grep过滤的Telnet控制台自动化
SSH自动化：通过Netmiko实现网络设备自动化（200多种设备类型）
网络拓扑：批量连接/断开链接、创建图形、导出图表
Docker集成：配置容器网络，读/写文件
工具发现: search_tools() 具有类别/能力/资源过滤功能
Claude桌面支持：可通过工具访问的所有资源(query_resource, list_projects, list_nodes, get_topology)
安全：API密钥认证（HTTP模式）、服务权限隔离、HTTPS支持

安装

支持的平台： 仅限Windows

快速入门（克劳德代码-推荐）

先决条件：

Windows 10/11
GNS3服务器正在运行且可访问
已安装克劳德代码
uv包管理器 （适用于uvx）：安装时 pip install uv 或从以下网址下载https://github.com/astral-sh/uv

选项1：使用uvx（推荐-更快）

# Single command - no .env file needed!
claude mcp add --transport stdio gns3-mcp `
  --env GNS3_HOST=192.168.1.20 `
  --env GNS3_PORT=80 `
  --env GNS3_USER=admin `
  --env GNS3_PASSWORD=your-password `
  --scope user `
  -- uvx gns3-mcp@latest

# Verify installation
claude mcp get gns3-mcp
# Should show: Status: ✓ Connected

选项2：使用pip（传统）

# Step 1: Install package
pip install gns3-mcp

# Step 2: Add to Claude Code with credentials
claude mcp add --transport stdio gns3-mcp `
  --env GNS3_HOST=192.168.1.20 `
  --env GNS3_PORT=80 `
  --env GNS3_USER=admin `
  --env GNS3_PASSWORD=your-password `
  --scope user `
  -- gns3-mcp

# Step 3: Verify installation
claude mcp get gns3-mcp
# Should show: Status: ✓ Connected

为什么是uvx？ 比pip快10-100倍，自动隔离依赖关系，无需venv管理。

编辑器安装

Claude Code (Detailed Setup)

Claude代码设置

STDIO模式（推荐）

STDIO模式更安全-无需HTTP服务，无需身份验证，仅在Claude Code处于活动状态时运行。

使用uvx（推荐）：

# 1. Install uv (one-time setup)
pip install uv

# 2. Create .env file
@"
GNS3_HOST=192.168.1.20
GNS3_PORT=80
GNS3_USER=admin
GNS3_PASSWORD=your-password
"@ | Out-File -FilePath .env -Encoding ASCII

# 3. Add to Claude Code
claude mcp add --transport stdio gns3-mcp --scope user -- uvx gns3-mcp@latest

# 4. Verify
claude mcp get gns3-mcp

使用pip：

# 1. Install package globally
pip install gns3-mcp

# 2. Create .env file in project directory
@"
GNS3_HOST=192.168.1.20
GNS3_PORT=80
GNS3_USER=admin
GNS3_PASSWORD=your-password
"@ | Out-File -FilePath .env -Encoding ASCII

# 3. Add to Claude Code
claude mcp add --transport stdio gns3-mcp --scope user -- gns3-mcp

# 4. Verify
claude mcp get gns3-mcp
# Should show: Status: ✓ Connected

环境变量：

变量	必填	描述	示例
`GNS3_HOST`	是	GNS3服务器IP/主机名	`192.168.1.20`
`GNS3_PORT`	是	GNS3服务器端口	`80` 或 `3080`
`GNS3_USER`	是	GNS3用户名	`admin`
`GNS3_PASSWORD`	是	GNS3密码	`your-password`

Claude Desktop (.mcpb Package)

Claude桌面设置

安装：

下载最新 .mcpb 包裹：
- 自发布
- 或者在本地构建： just build （创建 mcp-server\mcp-server.mcpb)
双击安装 这 .mcpb 文件
配置凭据 在克劳德桌面：
- 打开克劳德桌面
- 前往“设置”>“开发人员”>“编辑配置”
- 找到 gns3-mcp 服务器
- 添加环境变量：
```
{
  "GNS3_HOST": "192.168.1.20",
  "GNS3_PORT": "80",
  "GNS3_USER": "admin",
  "GNS3_PASSWORD": "your-password"
}
```
重新启动克劳德桌面

检查日志 如果出现问题：

C:\Users\<username>\AppData\Roaming\Claude\logs\mcp-server-GNS3 Lab Controller.log

Cursor & Windsurf (JSON Configuration)

光标设置

配置文件位置：

项目具体： .cursor\mcp.json （在项目目录中）
全球的： %USERPROFILE%\.cursor\mcp.json

使用uvx（推荐）：

安装紫外线： pip install uv
创建/编辑 .cursor\mcp.json:

{
  "mcpServers": {
    "gns3-mcp": {
      "command": "uvx",
      "args": ["gns3-mcp@latest"],
      "env": {
        "GNS3_HOST": "192.168.1.20",
        "GNS3_PORT": "80",
        "GNS3_USER": "admin",
        "GNS3_PASSWORD": "your-password"
      }
    }
  }
}

使用pip：

安装软件包： pip install gns3-mcp
创建/编辑 .cursor\mcp.json:

{
  "mcpServers": {
    "gns3-mcp": {
      "command": "gns3-mcp",
      "args": [],
      "env": {
        "GNS3_HOST": "192.168.1.20",
        "GNS3_PORT": "80",
        "GNS3_USER": "admin",
        "GNS3_PASSWORD": "your-password"
      }
    }
  }
}

重新启动游标

风帆设置

配置文件位置： %USERPROFILE%\.codeium\windsurf\mcp_config.json

使用uvx（推荐）：

安装紫外线： pip install uv
创建/编辑 mcp_config.json:

{
  "mcpServers": {
    "gns3-mcp": {
      "command": "uvx",
      "args": ["gns3-mcp@latest"],
      "env": {
        "GNS3_HOST": "192.168.1.20",
        "GNS3_PORT": "80",
        "GNS3_USER": "admin",
        "GNS3_PASSWORD": "your-password"
      }
    }
  }
}

使用pip：

安装软件包： pip install gns3-mcp
创建/编辑 mcp_config.json:

{
  "mcpServers": {
    "gns3-mcp": {
      "command": "gns3-mcp",
      "args": [],
      "env": {
        "GNS3_HOST": "192.168.1.20",
        "GNS3_PORT": "80",
        "GNS3_USER": "admin",
        "GNS3_PASSWORD": "your-password"
      }
    }
  }
}

重新启动Windsurf

注： Cursor和Windsurf使用相同的配置格式。

故障排除

连接问题：

# Test GNS3 server connectivity
curl http://192.168.1.20:80/v3/projects

# Check Claude Code MCP status
claude mcp get gns3-mcp

# View detailed logs (Claude Code)
# Check console output when running commands

常见问题：

“找不到gns3 mcp”：确保安装了软件包(pip list | findstr gns3-mcp)
“连接被拒绝”：验证GNS3服务器是否正在运行且可访问
“身份验证失败”：检查凭据 .env 文件
“插座已关闭”：SSH会话已过期，在下一个命令时自动重新连接

关于Claude Desktop的问题： 在以下位置查看日志：

C:\Users\<username>\AppData\Roaming\Claude\logs\mcp-server-GNS3 Lab Controller.log

高级设置

HTTP Mode (Always-Running Service)

HTTP模式配置

HTTP模式 需要持久服务和API密钥身份验证。仅在需要服务始终运行或从其他计算机访问网络时使用。

先决条件：

.env 带有GNS3凭据的文件
用于身份验证的API密钥

设置：

增添 .env:

# Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))"
MCP_API_KEY=your-random-token-here

配置克劳德代码：

claude mcp add --transport http gns3-mcp http://127.0.0.1:8100/mcp/ --scope user`
  --header "MCP_API_KEY: your-random-token-here"

启动服务器（在单独的终端中）：
```
gns3-mcp --transport http --http-port 8100
```

备注：如果 MCP_API_KEY 缺少 .env，它将在首次启动时自动生成并自动保存到 .env 为了坚持。

Windows Service (Production Deployment)

Windows服务部署

使用WinSW和uvx（用于HTTP模式）将MCP服务器作为Windows服务运行。

📖 看便携式设置.md 详细说明。

快速设置：

# 1. Install uv (if not already installed)
pip install uv

# 2. Set environment variables from .env (requires Administrator)
.\set-env-vars.ps1

# 3. Install and start service (requires Administrator)
.\server.cmd install

服务管理：

# Check status
.\server.cmd status

# Start/stop/restart
.\server.cmd start
.\server.cmd stop
.\server.cmd restart

# After code updates
.\server.cmd reinstall        # Reinstall service

# Remove service
.\server.cmd uninstall

# Development mode (direct run, no service)
.\server.cmd run

主要特点：

✅ 便携的：适用于任何文件夹位置（无硬编码路径）
✅ 没有venv：使用uvx进行自动隔离
✅ 安全：Windows环境变量中的凭据
✅ 简单：使用PowerShell脚本自动设置
用户：GNS3MCP服务（低权限，可选）
初创公司：自动
日志: mcp-http-server.log 和 GNS3-MCP-HTTP.wrapper.log

Development Setup (Contributors)

从源手动安装

要求：

Python≥3.10
GNS3服务器v3.x正在运行并可访问

设置：

# Install dependencies
pip install -r requirements.txt

# Create .env file
@"
GNS3_HOST=192.168.1.20
GNS3_PORT=80
GNS3_USER=admin
GNS3_PASSWORD=your-password
"@ | Out-File -FilePath .env -Encoding ASCII

# Run directly (STDIO mode - no authentication)
python gns3_mcp\cli.py --host 192.168.1.20 --port 80 --username admin --password your-password

# Or add to Claude Code (project-scoped)
claude mcp add --transport stdio gns3-mcp --scope project -- python "C:\full\path\to\gns3_mcp\cli.py"

构建.mcpb包：

just build
# Creates: mcp-server\mcp-server.mcpb

Docker部署

在Docker中运行GNS3 MCP Server，以实现隔离部署、更简单的管理和多平台支持。

Docker Compose快速入门

先决条件：

已安装Docker桌面
GNS3服务器正在运行且可访问
GNS3服务器的网络访问

第一步：下载docker-compose.yml

curl -O https://raw.githubusercontent.com/ChistokhinSV/gns3-mcp/master/docker-compose.yml

步骤2：创建.env文件

cat > .env <<EOF
GNS3_HOST=192.168.1.20
GNS3_PORT=80
GNS3_USER=admin
GNS3_PASSWORD=your-password
HTTP_PORT=8000
LOG_LEVEL=INFO
EOF

或从模板复制：

curl -O https://raw.githubusercontent.com/ChistokhinSV/gns3-mcp/master/.env.example
mv .env.example .env
# Edit .env with your credentials

步骤3：启动服务

# Start MCP server and SSH proxy
docker-compose up -d

# View logs
docker-compose logs -f

# Check health
curl http://localhost:8000/health
curl http://localhost:8022/health

步骤4：配置Claude桌面/代码

对于 克劳德代码 （HTTP模式）：

claude mcp add --transport http gns3-mcp --url http://localhost:8000

对于 克劳德桌面，添加到MCP配置中：

{
  "mcpServers": {
    "gns3-mcp": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8000"
      }
    }
  }
}

使用Docker Run（不使用compose）

docker run -d \
  --name gns3-mcp-server \
  -p 8000:8000 \
  -e GNS3_HOST=192.168.1.20 \
  -e GNS3_PORT=80 \
  -e GNS3_USER=admin \
  -e GNS3_PASSWORD=your-password \
  --restart unless-stopped \
  chistokhinsv/gns3-mcp:latest

容器管理

# View logs
docker-compose logs -f gns3-mcp
docker-compose logs -f ssh-proxy

# Restart services
docker-compose restart

# Stop services
docker-compose down

# Update to latest version
docker-compose pull
docker-compose up -d

环境变量

变量	必填	默认	描述
`GNS3_HOST`	是	-	GNS3服务器IP/主机名
`GNS3_PORT`	没有	`80`	GNS3 API端口
`GNS3_USER`	是	-	GNS3用户名
`GNS3_PASSWORD`	是	-	GNS3密码
`HTTP_PORT`	没有	`8000`	MCP服务器端口
`LOG_LEVEL`	没有	`INFO`	日志记录级别
`GNS3_USE_HTTPS`	没有	`false`	GNS3使用HTTPS
`GNS3_VERIFY_SSL`	没有	`true`	验证SSL证书

看 .env.示例查看完整列表。

建筑

Docker部署包括两个容器：

gns3 mcp -主MCP服务器（端口8000）
- 提供对GNS3的MCP协议访问
- HTTP/SSE传输模式
- 网桥网络模式
gns3 ssh代理 -SSH网关（端口8022）
- 允许SSH访问实验室设备
- 主机网络模式（隔离实验室网络所需）
- 基于Netmiko的自动化

故障排除

容器无法启动：

docker-compose logs gns3-mcp
docker-compose logs ssh-proxy

无法连接到GNS3：

# Test from container
docker exec gns3-mcp-server curl -v http://192.168.1.20/v3/version

# Check connectivity
docker exec gns3-mcp-server ping -c 3 192.168.1.20

健康检查失败：

# Manual health check
curl -v http://localhost:8000/health

# Check container status
docker ps --filter name=gns3-mcp

有关更多详细信息，请参阅 docs/DOCKER_HUB.md.

文档

更改日志.md -版本历史和发行说明
部署.md -SSH代理部署说明
文档/架构/ -架构文件和C4图

许可证

MIT许可证

作者

谢尔盖·奇斯托金(Sergei@Chistokhin.com)

使用说明

GNS3 MCP服务器

特性

安装

快速入门（克劳德代码-推荐）

编辑器安装

Claude代码设置

Claude桌面设置

光标设置

风帆设置

故障排除

高级设置

HTTP模式配置

Windows服务部署

从源手动安装

Docker部署

Docker Compose快速入门

使用Docker Run（不使用compose）

容器管理

环境变量

建筑

故障排除

文档

许可证

作者

相关 MCP

小度智能终端

智能家居设备控制服务器

iPhone自动化服务器

智能家居控制MCP服务器

网络运维整合平台

ADB控制服务