Skip to main content
Glama

gns3-mcp

A full-feature MCP server for the GNS3 v3 (3.0) controller REST API. It lets an AI agent (Claude Code / Claude Desktop / any MCP client) drive a GNS3 network-emulation lab end-to-end: build topologies, manage device lifecycle, snapshot, capture packets, manage templates / computes / images / RBAC, and automate device CLIs over node consoles.

Built with Python + FastMCP. Ships as a Claude Code plugin and as a standalone pip-installable MCP server. ~125 tools, 4 resources, and 3 prompts.

Features

Area

Tools

Controller

version, statistics, reload/shutdown, IOU license

Projects

CRUD, open/close/load, duplicate, export/import, lock, files

Nodes

CRUD, create-from-template, start/stop/suspend/reload (single + all), isolate, duplicate, idle-PC, disk/files

Links

CRUD, filters, reset

Console automation

node_console_send, node_console_session, node_console_read, node_console_info (telnet)

Packet capture

start/stop, Wireshark restart, pcap download

Snapshots

list / create / restore / delete

Drawings

canvas annotations CRUD

Templates / Appliances

CRUD + duplicate; browse & install appliance catalog

Computes / Images

manage compute servers, query emulators; upload/install/prune images

RBAC

users, groups, roles, privileges, ACL

Resource pools

CRUD + membership

Resources

gns3://projects, gns3://templates, gns3://computes, gns3://project/{id}/topology

Prompts

build_lab, troubleshoot_node, snapshot_before_change

Related MCP server: GNS3 MCP Server

Configuration

All settings come from the environment (prefix GNS3_):

Variable

Default

Purpose

GNS3_BASE_URL

http://localhost:3080

Controller URL (no /v3)

GNS3_USERNAME / GNS3_PASSWORD

–

Login credentials

GNS3_TOKEN

–

Pre-issued bearer token (skips login)

GNS3_VERIFY_TLS

true

Verify TLS for https

GNS3_DEFAULT_PROJECT

–

Project id used when a tool omits project_id

GNS3_READ_ONLY

false

Disable all mutating tools (41 read-only tools remain)

GNS3_TRANSPORT

stdio

stdio or http

GNS3_HTTP_HOST / GNS3_HTTP_PORT

127.0.0.1 / 8080

HTTP bind

GNS3_CONSOLE_TIMEOUT

15

Console read timeout (s)

Install

As a Claude Code plugin

/plugin marketplace add /home/oscar/Code/gns3-mcp
/plugin install gns3

The plugin declares the MCP server in plugin/.mcp.json; it runs the gns3-mcp console script, so install the package first (below) or adjust the command to python -m gns3_mcp.

As a standalone MCP server

pip install -e .            # from this repo (or, once published: pipx install gns3-mcp-server)

The PyPI distribution is named gns3-mcp-server; it installs the gns3-mcp console script (and a gns3-mcp-server alias, so uvx gns3-mcp-server works too).

Register with Claude Code:

claude mcp add gns3 -- gns3-mcp
# then set env: GNS3_BASE_URL, GNS3_USERNAME, GNS3_PASSWORD

Or in Claude Desktop config:

{
  "mcpServers": {
    "gns3": {
      "command": "gns3-mcp",
      "env": {
        "GNS3_BASE_URL": "http://localhost:3080",
        "GNS3_USERNAME": "admin",
        "GNS3_PASSWORD": "your-password"
      }
    }
  }
}

Run as a remote HTTP server instead:

GNS3_TRANSPORT=http GNS3_HTTP_PORT=8080 gns3-mcp

Safety

  • GNS3_READ_ONLY=true registers only read-only tools.

  • Destructive tools (project_delete, node_delete via flow, controller_shutdown, controller_reload, images_prune) require an explicit confirm=true.

  • Console automation can run arbitrary commands on emulated devices — treat it like shell access to your lab.

Development

pip install -e ".[dev]"
python -m pytest                 # hermetic unit + tool + console tests (respx-mocked)

# Opt-in live smoke test against a real controller:
GNS3_LIVE=1 GNS3_BASE_URL=http://localhost:3080 \
  GNS3_USERNAME=admin GNS3_PASSWORD=... python -m pytest tests/test_live_smoke.py -s

Architecture: a single async GNS3Client (client.py) handles login, 401 re-auth, pagination, and binary I/O; every tool module under tools/ is a thin layer over it and exposes register(mcp). console.py is a minimal telnet proxy for driving node consoles.

Contributing & releases

Commits follow Conventional Commits (feat:, fix:, feat!: for breaking changes), which drives automated versioning. release-please opens a release PR that bumps the version and updates CHANGELOG.md; merging it tags a release and publishes to PyPI via Trusted Publishing (after the test suite passes). Full details in CONTRIBUTING.md.

Available Tools

122 tools
acl_createB

Create an ACE binding a user or group to a role on a resource path.

ace_type is 'user' or 'group'; provide the matching user_id or group_id.

Inputs: path (required), ace_type (required), role_id (required), propagate, +2 more. Returns: object

acl_deleteC

Delete an ACE.

Inputs: ace_id (required). Returns: Generic wrapper for non-object return types.

acl_endpointsA

List the endpoints (resources) that ACEs can be attached to.

Inputs: no named parameters. Returns: Generic wrapper for non-object return types.

acl_listC

List Access Control Entries (ACEs) in the ACL.

Inputs: limit. Returns: Generic wrapper for non-object return types.

acl_updateD

Update an ACE.

Inputs: ace_id (required), updates (required). Returns: object

appliance_getA

Get full details for an appliance (versions, images required).

Inputs: appliance_id (required). Returns: object

appliance_installC

Install an appliance as a template (optionally a specific version).

Inputs: appliance_id (required), version. Returns: object

appliances_listB

List appliances from the GNS3 catalog. Set update=true to refresh from registry.

Inputs: update, symbol_theme, limit. Returns: Generic wrapper for non-object return types.

capture_downloadB

Download the current/last pcap capture file for a link to dest_path.

Inputs: link_id (required), dest_path (required), project_id. Returns: Generic wrapper for non-object return types.

capture_startC

Start a packet capture on a link (DLT_EN10MB for Ethernet).

Inputs: link_id (required), data_link_type, capture_file_name, project_id. Returns: object

capture_stopC

Stop the packet capture on a link.

Inputs: link_id (required), project_id. Returns: Generic wrapper for non-object return types.

capture_wireshark_restartC

Restart the live Wireshark capture stream on a link.

Inputs: link_id (required), project_id. Returns: Generic wrapper for non-object return types.

compute_createB

Register a compute server. compute needs protocol/host/port/name (+ auth).

Inputs: compute (required). Returns: object

compute_deleteC

Unregister a compute server.

Inputs: compute_id (required). Returns: Generic wrapper for non-object return types.

compute_emulator_queryB

Query an emulator on a compute, e.g. emulator='docker' action='images', emulator='virtualbox' action='vms', emulator='vmware' action='vms'.

Inputs: compute_id (required), emulator (required), action (required).

compute_getC

Get full details for a compute server.

Inputs: compute_id (required). Returns: object

computes_listB

List compute servers (id, name, host, connected state, load).

Inputs: limit. Returns: Generic wrapper for non-object return types.

compute_updateC

Update a compute server's connection settings.

Inputs: compute_id (required), updates (required). Returns: object

controller_reloadA

Reload the GNS3 controller. Requires confirm=true.

Inputs: confirm. Returns: Generic wrapper for non-object return types.

controller_shutdownA

Shut down the GNS3 controller process. Requires confirm=true. Destructive.

Inputs: confirm. Returns: Generic wrapper for non-object return types.

drawing_createB

Create a drawing from an SVG string at canvas position (x, y).

Inputs: svg (required), x, y, z, +1 more. Returns: object

drawing_deleteC

Delete a drawing.

Inputs: drawing_id (required), project_id. Returns: Generic wrapper for non-object return types.

drawings_listC

List drawings (SVG annotations) in a project.

Inputs: project_id, limit. Returns: Generic wrapper for non-object return types.

drawing_updateB

Update a drawing (svg/x/y/z/rotation).

Inputs: drawing_id (required), updates (required), project_id. Returns: object

group_createC

Create a user group.

Inputs: name (required). Returns: object

group_deleteC

Delete a user group.

Inputs: group_id (required). Returns: Generic wrapper for non-object return types.

group_member_addC

Add a user to a group.

Inputs: group_id (required), user_id (required). Returns: Generic wrapper for non-object return types.

group_member_removeB

Remove a user from a group.

Inputs: group_id (required), user_id (required). Returns: Generic wrapper for non-object return types.

group_membersC

List members of a user group.

Inputs: group_id (required). Returns: Generic wrapper for non-object return types.

groups_listC

List user groups.

Inputs: limit. Returns: Generic wrapper for non-object return types.

group_updateC

Update a user group.

Inputs: group_id (required), updates (required). Returns: object

image_deleteC

Delete an image by path.

Inputs: image_path (required). Returns: Generic wrapper for non-object return types.

image_getA

Get metadata for an image by its path.

Inputs: image_path (required). Returns: object

image_installC

Install/register images so templates can use them (optionally one path).

Inputs: image_path.

images_listB

List disk images known to the controller (qemu/ios/iou/docker).

Inputs: limit. Returns: Generic wrapper for non-object return types.

images_pruneA

Delete all images not used by any template. Requires confirm=true.

Inputs: confirm. Returns: Generic wrapper for non-object return types.

image_uploadC

Upload a local image file to the controller under image_path.

Inputs: image_path (required), src_path (required). Returns: object

iou_license_setB

Set the Cisco IOU license. iourc_content is the raw iourc file text.

Inputs: iourc_content (required), license_check. Returns: object

node_console_infoC

Return console connection info for a node (host, port, type).

Inputs: node_id (required), project_id. Returns: object

node_console_readB

Connect and drain any pending console output without sending a command.

Inputs: node_id (required), project_id, idle, max_wait. Returns: Generic wrapper for non-object return types.

node_console_resetC

Reset the console server connection for a node.

Inputs: node_id (required), project_id. Returns: Generic wrapper for non-object return types.

node_console_sendA

Send a single command to a node's telnet console and return the output.

Reads until the console is idle for idle seconds (or max_wait total). Sends a blank line first to capture the current prompt.

Inputs: node_id (required), command (required), project_id, idle, +1 more. Returns: Generic wrapper for non-object return types.

node_console_sessionA

Run a sequence of commands on a node console in one connection.

Returns a list of {command, output} entries. Useful for entering config mode and applying several lines (e.g. ['enable', 'conf t', 'interface g0/0', 'ip address ...']).

Inputs: node_id (required), commands (required), project_id, idle, +1 more. Returns: Generic wrapper for non-object return types.

node_createA

Create a node directly (node_type e.g. vpcs, qemu, docker, dynamips, ethernet_switch).

Prefer node_create_from_template when a suitable template exists.

Inputs: name (required), node_type (required), compute_id, properties, +4 more. Returns: object

node_create_from_templateB

Instantiate a node from a template at canvas position (x, y).

Inputs: template_id (required), x, y, name, +2 more. Returns: object

node_deleteC

Delete a node from the project.

Inputs: node_id (required), project_id. Returns: Generic wrapper for non-object return types.

node_duplicateB

Duplicate a node, offset by (dx, dy) on the canvas.

Inputs: node_id (required), dx, dy, project_id. Returns: object

node_file_readC

Read a text file from inside a node's working directory.

Inputs: node_id (required), file_path (required), project_id. Returns: Generic wrapper for non-object return types.

node_file_writeB

Write a text file into a node's working directory (e.g. startup-config).

Inputs: node_id (required), file_path (required), content (required), project_id. Returns: Generic wrapper for non-object return types.

node_getC

Get full details for a single node.

Inputs: node_id (required), project_id. Returns: object

node_idlepc_autoC

Auto-compute a Dynamips idle-PC value for a node.

Inputs: node_id (required), project_id. Returns: object

node_idlepc_proposalsC

Get Dynamips idle-PC proposals for a node.

Inputs: node_id (required), project_id. Returns: Generic wrapper for non-object return types.

node_isolateB

Isolate a node: suspend all its links (cut traffic without deleting links).

Inputs: node_id (required), project_id. Returns: Generic wrapper for non-object return types.

node_reloadC

Reload (restart) a node.

Inputs: node_id (required), project_id. Returns: Generic wrapper for non-object return types.

nodes_listC

List nodes in a project (id, name, type, status, console).

Inputs: project_id, limit. Returns: Generic wrapper for non-object return types.

nodes_reload_allC

Reload every node in the project.

Inputs: project_id. Returns: Generic wrapper for non-object return types.

nodes_start_allC

Start every node in the project.

Inputs: project_id. Returns: Generic wrapper for non-object return types.

nodes_stop_allC

Stop every node in the project.

Inputs: project_id. Returns: Generic wrapper for non-object return types.

nodes_suspend_allC

Suspend every node in the project.

Inputs: project_id. Returns: Generic wrapper for non-object return types.

node_startD

Start a node.

Inputs: node_id (required), project_id. Returns: Generic wrapper for non-object return types.

node_stopC

Stop a node.

Inputs: node_id (required), project_id. Returns: Generic wrapper for non-object return types.

node_suspendD

Suspend a node.

Inputs: node_id (required), project_id. Returns: Generic wrapper for non-object return types.

node_unisolateB

Re-enable all links on a previously isolated node.

Inputs: node_id (required), project_id. Returns: Generic wrapper for non-object return types.

node_updateC

Update node attributes (e.g. {"name": "...", "properties": {...}}).

Inputs: node_id (required), updates (required), project_id. Returns: object

pool_createC

Create a resource pool.

Inputs: name (required). Returns: object

pool_deleteC

Delete a resource pool.

Inputs: pool_id (required). Returns: Generic wrapper for non-object return types.

pool_getC

Get a resource pool.

Inputs: pool_id (required). Returns: object

pool_resource_addC

Add a resource (project/template/compute id) to a pool.

Inputs: pool_id (required), resource_id (required). Returns: Generic wrapper for non-object return types.

pool_resource_removeC

Remove a resource from a pool.

Inputs: pool_id (required), resource_id (required). Returns: Generic wrapper for non-object return types.

pool_resourcesC

List the resources contained in a pool.

Inputs: pool_id (required). Returns: Generic wrapper for non-object return types.

pools_listC

List resource pools.

Inputs: limit. Returns: Generic wrapper for non-object return types.

pool_updateC

Update a resource pool (e.g. rename).

Inputs: pool_id (required), updates (required). Returns: object

privileges_listC

List all assignable privileges in the system.

Inputs: limit. Returns: Generic wrapper for non-object return types.

project_closeA

Close an open project (stops nodes, frees resources).

Inputs: project_id. Returns: Generic wrapper for non-object return types.

project_createB

Create a new project. Optionally pin a specific project_id (UUID).

Inputs: name (required), auto_open, auto_start, project_id. Returns: object

project_deleteA

Delete a project permanently. Requires confirm=true. Destructive.

Inputs: project_id (required), confirm. Returns: Generic wrapper for non-object return types.

project_duplicateC

Duplicate a project under a new name.

Inputs: project_id, name, reset_mac_addresses. Returns: object

project_exportC

Export a project to a local .gns3project archive at dest_path.

Inputs: dest_path (required), project_id, include_images, include_snapshots, +1 more. Returns: Generic wrapper for non-object return types.

project_file_readC

Read a text file from inside the project directory.

Inputs: file_path (required), project_id. Returns: Generic wrapper for non-object return types.

project_file_writeC

Write a text file inside the project directory.

Inputs: file_path (required), content (required), project_id. Returns: Generic wrapper for non-object return types.

project_getC

Get full details for a project.

Inputs: project_id. Returns: object

project_importC

Import a project from a local .gns3project archive.

Inputs: src_path (required), name. Returns: object

project_loadB

Load a project from a .gns3 file path on the controller host.

Inputs: path (required). Returns: object

project_lockC

Lock a project to prevent topology edits.

Inputs: project_id. Returns: Generic wrapper for non-object return types.

project_lockedC

Return whether the project is currently locked.

Inputs: project_id. Returns: Generic wrapper for non-object return types.

project_openB

Open a closed project so its nodes can run.

Inputs: project_id. Returns: object

projects_listB

List all projects on the controller (id, name, status).

Inputs: limit. Returns: Generic wrapper for non-object return types.

project_statsB

Get node/link/drawing/snapshot counts for a project.

Inputs: project_id. Returns: object

project_unlockD

Unlock a project.

Inputs: project_id. Returns: Generic wrapper for non-object return types.

project_updateC

Update project attributes (e.g. {"name": "...", "auto_start": true}).

Inputs: project_id, updates. Returns: object

role_createD

Create a role.

Inputs: name (required), description. Returns: object

role_deleteC

Delete a role.

Inputs: role_id (required). Returns: Generic wrapper for non-object return types.

role_privilege_grantC

Grant a privilege to a role.

Inputs: role_id (required), privilege_id (required). Returns: Generic wrapper for non-object return types.

role_privilege_revokeC

Revoke a privilege from a role.

Inputs: role_id (required), privilege_id (required). Returns: Generic wrapper for non-object return types.

role_privilegesC

List the privileges granted to a role.

Inputs: role_id (required). Returns: Generic wrapper for non-object return types.

roles_listC

List roles.

Inputs: limit. Returns: Generic wrapper for non-object return types.

role_updateC

Update a role.

Inputs: role_id (required), updates (required). Returns: object

snapshot_createC

Create a snapshot of the current project state.

Inputs: name (required), project_id. Returns: object

snapshot_deleteC

Delete a snapshot.

Inputs: snapshot_id (required), project_id. Returns: Generic wrapper for non-object return types.

snapshot_restoreC

Restore the project to a snapshot. The current state is overwritten.

Inputs: snapshot_id (required), project_id. Returns: object

snapshots_listC

List snapshots of a project.

Inputs: project_id, limit. Returns: Generic wrapper for non-object return types.

template_createC

Create a template. template must include name and template_type plus props.

Inputs: template (required). Returns: object

template_deleteC

Delete a template.

Inputs: template_id (required). Returns: Generic wrapper for non-object return types.

template_duplicateC

Duplicate a template.

Inputs: template_id (required). Returns: object

template_getB

Get full details for a template (all properties).

Inputs: template_id (required). Returns: object

templates_listC

List device templates (id, name, type, category).

Inputs: limit. Returns: Generic wrapper for non-object return types.

template_updateC

Update a template's attributes.

Inputs: template_id (required), updates (required). Returns: object

user_createC

Create a user account.

Inputs: username (required), password (required), email, full_name, +1 more. Returns: object

user_deleteC

Delete a user account.

Inputs: user_id (required). Returns: Generic wrapper for non-object return types.

user_getC

Get a user account.

Inputs: user_id (required). Returns: object

user_groupsC

List the groups a user belongs to.

Inputs: user_id (required). Returns: Generic wrapper for non-object return types.

users_listC

List user accounts.

Inputs: limit. Returns: Generic wrapper for non-object return types.

user_updateB

Update a user (password, email, is_active, ...).

Inputs: user_id (required), updates (required). Returns: object

whoamiA

Return the currently authenticated user.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 122 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose, organized by resource type (acl, appliance, node, project, etc.) with descriptive names. Even within high-volume groups like node tools, actions such as start, stop, suspend, reload, isolate are unambiguous.

    Naming Consistency5/5

    Tool names consistently follow a prefix_resource_action pattern in snake_case (e.g., acl_create, node_start, project_delete). The only outlier is 'whoami', but it's a single exception.

    Tool Count2/5

    With 122 tools, the count far exceeds typical well-scoped ranges (3-15). While GNS3 is complex, this volume is overwhelming and likely to cause navigation issues for agents.

    Completeness5/5

    The tool set covers the full lifecycle of GNS3 operations: projects, nodes, templates, links, captures, images, appliances, users, ACLs, roles, pools, snapshots, and console interaction. No obvious gaps for basic simulation workflows.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI-powered network engineering by providing natural language control over GNS3 network simulations. Supports creating projects, building network topologies, managing devices, controlling simulations, and analyzing network traffic through conversational AI interactions.
      42
      28
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables programmatic control of a PNETLab network-emulation lab via natural language, allowing users to build topologies, wire links, push device configs, and boot the lab through an LLM agent.
      31
      6
      Apache 2.0