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 /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": [
        "//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

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

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

工具错误

问题：工具返回错误消息

解决方案:

1. 检查克劳德日志：

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

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

   List all projects first to get valid project IDs

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

模板问题

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

解决方案:

1. 首先列出可用模板：

   List all available templates

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

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

添加新工具

1. 添加方法 GNS3Client 在 gns3_client.py
2. 添加 @mcp.tool() 装饰功能到相应的工具模块：

- 工具/项目工具.py 用于项目运营 - 用于节点操作 - 工具/link_tools.py 用于链接操作 - 工具/template_tools.py 用于模板操作 - 或者在中创建一个新模块 tools/ 对于新类别

1. 在模块中注册新工具 register_*_tools() 函数
2. 使用新的工具文档更新此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集成
• 全面的错误处理