AI导哈

GNS3网络拓扑控制服务器

GNS3 MCP服务器是一个通过Claude Code和Claude Desktop控制GNS3网络拓扑的工具，提供项目管理、节点操作、链接管理和拓扑控制等功能。

  • by JMartinCreuzburg
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 JMartinCreuzburg/gns3_over_mcp

使用说明

GNS3 MCP服务器

模型上下文协议（MCP）服务器，用于通过Claude Code和Claude Desktop控制GNS3网络拓扑。

特性

  • 项目管理：创建、打开、关闭、删除GNS3项目
  • 节点操作：添加、删除、启动、停止网络节点（VM、路由器、交换机）
  • 链路管理：创建和删除节点之间的连接
  • 拓扑控制：启动/停止项目中的所有节点
  • 状态监测：获取项目统计数据和当前状态

需求

  • Python 3.12.3+
  • GNS3服务器2.2.55（本地或远程）
  • FastMCP 2.0+
  • 克劳德代码或克劳德桌面

安装

1.克隆存储库

cd <<path>>/gns3_over_mcp

2.创建虚拟环境

python3 -m venv venv
source venv/bin/activate

3.安装依赖项

pip install -r requirements.txt

4.配置GNS3连接

创建 gns3_config.json （已存在，具有默认的localhost设置）：

{
  "gns3": {
    "host": "localhost",
    "port": 3080,
    "protocol": "http",
    "verify_ssl": true,
    "timeout": 30,
    "auth_required": false
  }
}

对于具有身份验证的远程服务器，请创建 .env:

cp .env.example .env
# Edit .env and add your credentials:
# GNS3_USERNAME=your_username
# GNS3_PASSWORD=your_password
# GNS3_AUTH_REQUIRED=true

与Claude整合

克劳德桌面

增添 ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gns3": {
      "command": "python3",
      "args": [
        "/<<path>>/gns3_over_mcp/gns3_mcp_server.py"
      ]
    }
  }
}

更新配置后重新启动Claude Desktop。

克劳德代码

如果您通过以下方式配置服务器，Claude Code将自动发现它：

# Add to Claude Code MCP configuration
# The examples/claude_code_config.json shows the format

可用工具

MCP服务器提供18个工具：

项目管理（6个工具）

  • create_project -创建新的GNS3项目
  • list_projects -列出所有项目
  • get_project -按ID获取项目详细信息
  • open_project -打开一个已关闭的项目
  • close_project -关闭打开的项目
  • delete_project -永久删除项目

节点管理（5个工具）

  • list_nodes -列出项目中的所有节点
  • create_node -创建新节点（VM、路由器、交换机等）
  • delete_node -从项目中删除节点
  • start_node -启动特定节点
  • stop_node -停止特定节点

链接管理（3个工具）

  • list_links -列出项目中的所有链接
  • create_link -在两个节点之间创建链接
  • delete_link -删除链接

拓扑操作（4个工具）

  • start_all_nodes -启动项目中的所有节点
  • stop_all_nodes -停止项目中的所有节点
  • get_project_stats -获取统计数据（节点计数、链接计数、状态）
  • list_templates -列出可用节点模板

使用示例

通过克劳德代码或克劳德桌面

配置后，您可以通过自然语言与GNS3交互：

Create a new GNS3 project called "NetworkLab"

List all available templates

Add two VPCS nodes named PC1 and PC2 to the project

Create a link between PC1 port 0 and PC2 port 0

Start all nodes in the project

Get statistics for the current project

Stop all nodes and close the project

建筑

文件结构

gns3_over_mcp/
├── gns3_mcp_server.py      # Main MCP server entry point
├── gns3_client.py          # GNS3 REST API client wrapper
├── config.py               # Configuration management
├── tools/                  # Modular tool definitions
│   ├── __init__.py         # Tool module exports
│   ├── project_tools.py    # Project management (7 tools)
│   ├── node_tools.py       # Node operations (7 tools)
│   ├── link_tools.py       # Link management (3 tools)
│   └── template_tools.py   # Template operations (1 tool)
├── gns3_config.json        # GNS3 connection settings
├── .env                    # Environment variables (sensitive data)
├── .env.example            # Template for .env
├── requirements.txt        # Python dependencies
├── examples/               # Example configurations
│   ├── claude_desktop_config.json
│   └── claude_code_config.json
└── README.md               # This file

配置优先级

服务器使用三层配置系统：

  1. 环境变量 （最高优先级）
  2. gns3_configure.json 文件
  3. 默认值 （最低优先级）

这使您能够：

  • 将连接设置存储在 gns3_config.json
  • 为不同环境覆盖环境变量
  • 将敏感数据（密码）保存在 .env 文件

故障排除

连接问题

问题：无法连接到GNS3服务器

解决方案:

  1. 验证GNS3服务器是否正在运行：

    curl http://localhost:3080/v2/version

  2. 检查 gns3_config.json 设置与GNS3服务器配置匹配

  3. 对于远程服务器，请确保在中配置了身份验证 .env

工具错误

问题：工具返回错误消息

解决方案:

  1. 检查克劳德日志：

    • Linux： ~/.config/Claude/logs/
    • 检查连接错误或API响应问题

  2. 验证项目ID和节点ID是否正确：

    List all projects first to get valid project IDs

  3. 确保GNS3服务器具有必要的权限和资源

模板问题

问题：无法使用特定模板创建节点

解决方案:

  1. 首先列出可用模板：

    List all available templates

  2. 使用正确的 template_id 从模板列表中

  3. 验证模板是否正确安装在GNS3中

添加新工具

  1. 添加方法 GNS3Client 在 gns3_client.py
  2. 添加 @mcp.tool() 装饰功能到相应的工具模块：
  3. 在模块中注册新工具 register_*_tools() 函数
  4. 使用新的工具文档更新此README

未来的增强功能

未来版本的潜在功能：

  • 快照管理（创建、还原、删除快照）
  • 控制台访问流
  • 数据包捕获集成
  • 节点配置导入/导出
  • 多项目批量操作
  • 实时状态通知
  • 网络图导出
  • 支持GNS3计算节点

许可证

MIT许可证

支持

对于问题或疑问：

  • 检查GNS3文档：https://docs.gns3.com/
  • 查看FastMCP文档：https://gofastmcp.com/
  • GNS3 API文件：https://gns3-server.readthedocs.io/

贡献

欢迎投稿！拜托：

  1. 复刻仓库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

版本历史记录

v0.2.0（当前）

  • 将服务器重构为模块化架构
  • 组织成语义模块（项目、节点、链接、模板）的工具
  • 提高了可维护性和可扩展性
  • 将主服务器文件从459行减少到42行

v0.1.0（初始版本）

  • 18个用于GNS3控制的MCP工具
  • 支持项目、节点、链接和拓扑操作
  • 使用环境变量进行配置管理
  • Claude Code和Claude Desktop集成
  • 全面的错误处理

相关 MCP