gns3 MCP

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

环境变量：

Claude Desktop (.mcpb Package)

Claude桌面设置

安装：

1. 下载最新 .mcpb 包裹：

- 自 发布 - 或者在本地构建： just build （创建 mcp-server\mcp-server.mcpb)

1. 双击安装 这 .mcpb 文件

1. 配置凭据 在克劳德桌面：

- 打开克劳德桌面 - 前往“设置”>“开发人员”>“编辑配置” - 找到 gns3-mcp 服务器 - 添加环境变量：

     {
       "GNS3_HOST": "192.168.1.20",
       "GNS3_PORT": "80",
       "GNS3_USER": "admin",
       "GNS3_PASSWORD": "your-password"
     }

1. 重新启动克劳德桌面

1. 检查日志 如果出现问题：

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

Cursor & Windsurf (JSON Configuration)

光标设置

配置文件位置：

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

使用uvx（推荐）：

1. 安装紫外线： pip install uv

1. 创建/编辑 .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：

1. 安装软件包： pip install gns3-mcp

1. 创建/编辑 .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"
      }
    }
  }
}

1. 重新启动游标

______________________________________________________________________

风帆设置

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

使用uvx（推荐）：

1. 安装紫外线： pip install uv

1. 创建/编辑 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：

1. 安装软件包： pip install gns3-mcp

1. 创建/编辑 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"
      }
    }
  }
}

1. 重新启动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\\AppData\Roaming\Claude\logs\mcp-server-GNS3 Lab Controller.log

______________________________________________________________________

高级设置

HTTP Mode (Always-Running Service)

HTTP模式配置

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

先决条件：

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

设置：

1. 增添 .env:

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

1. 配置克劳德代码：

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

1. 启动服务器（在单独的终端中）：

   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

环境变量

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

建筑

Docker部署包括两个容器：

1. gns3 mcp -主MCP服务器（端口8000）

- 提供对GNS3的MCP协议访问 - HTTP/SSE传输模式 - 网桥网络模式

1. 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

有关更多详细信息，请参阅 .

______________________________________________________________________

文档

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

许可证

MIT许可证

作者

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