Skip to main content
Glama

gns3-lab-mcp

An MCP server that lets an AI agent build real network labs in GNS3: create a project, add routers, switches, and hosts from the templates your GNS3 server already has, cable their ports together, start them, and hand back a Mermaid diagram of the result. It wraps the GNS3 controller's REST API through gns3fy, turns every response into clean JSON (or a friendly Error: ... string), and ships an agent skill that teaches the complete lab-design workflow.

The distribution is named gns3-lab-mcp on PyPI (not yet published — install from source below); the import package is gns3_mcp.

Demo: GIF placeholder — an agent creating the two-router OSPF lab from SKILL.md, then rendering the diagram below.

graph TD
    n0["R1"]
    n1["R2"]
    n0 --- n1

Requirements

  • GNS3 2.2 or newer, with its controller reachable over HTTP (default http://localhost:3080). GNS3_BASE_URL may include or omit a trailing /v2.

  • Node templates with their images installed on that controller — the server can list and add nodes, but it cannot install images.

  • No local Python install is needed: uvx fetches and runs the package.

Related MCP server: GNS3 MCP Server

Install

uvx gns3-lab-mcp

The console script starts the MCP server on stdio. Point it at a GNS3 controller other than the default with:

GNS3_BASE_URL=http://192.168.1.10:3080 uvx gns3-lab-mcp

Client configuration

OpenCode

Add this to opencode.json (project or global):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gns3": {
      "type": "local",
      "command": ["uvx", "gns3-lab-mcp"],
      "enabled": true,
      "environment": {
        "GNS3_BASE_URL": "http://localhost:3080"
      }
    }
  }
}

Claude Code

Add this to .mcp.json in the project root, or use claude mcp add:

{
  "mcpServers": {
    "gns3": {
      "command": "uvx",
      "args": ["gns3-lab-mcp"],
      "env": {
        "GNS3_BASE_URL": "http://localhost:3080"
      }
    }
  }
}

Tools

Every tool returns text. Mutating tools return the created or changed object as indented JSON; failures come back as a string starting with Error: rather than raising.

Error handling is deliberately split: failures to reach the controller say cannot reach GNS3 server at <url> (with the is gns3server running? hint on gns3_version), a request that hangs for 30 seconds says timed out contacting GNS3 server at <url>, and a controller that answers with an HTTP error returns GNS3's own message — for example node name already used in this project, without the status-code prefix gns3fy adds.

Tool

Arguments

Returns

ping

—

pong when the MCP server is alive

gns3_version

—

GNS3 server version information

list_projects

—

JSON list of {project_id, name, status}

create_project

name

JSON {project_id, name, status}

open_project

project_id

JSON {project_id, status: "opened"}; already-open projects are left alone

list_templates

—

JSON list of {template_id, name, category}

list_nodes

project_id

JSON list of {node_id, name, status, node_type}

add_node

project_id, template_id, name

JSON node {node_id, name, status, node_type}

start_node

project_id, node_id

JSON {project_id, node_id, status: "started"}

stop_node

project_id, node_id

JSON {project_id, node_id, status: "stopped"}

add_link

project_id, node_a_id, adapter_a, port_a, node_b_id, adapter_b, port_b

JSON link {link_id, node_ids}

list_links

project_id

JSON list of {link_id, node_ids}

draw_topology

project_id

Mermaid graph TD diagram as text

Notes:

  • add_node has no position arguments: nodes are created at canvas position (0, 0) and overlap until moved in the GNS3 GUI. draw_topology is unaffected — it draws from nodes and links, not coordinates.

  • Link ports are zero-based (adapter_a=0, port_a=0 is the first port on the first adapter). GNS3 rejects a port that is already in use.

  • The server does not configure devices, open consoles, delete objects, or take snapshots.

Agent skill

SKILL.md is an Agent-Skills-standard skill named gns3-lab-designer. It covers template discovery, the build workflow, naming conventions (R1, R2, SW1), a worked two-router OSPF example, and troubleshooting. Install it by copying it into your agent's skills directory, for example:

mkdir -p ~/.claude/skills/gns3-lab-designer
cp SKILL.md ~/.claude/skills/gns3-lab-designer/SKILL.md

Development

uv sync
uv run pytest tests/ -v

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers