gns3-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gns3-mcp Build a lab with two Cisco routers connected via Ethernet."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
|
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 |
|
Prompts |
|
Related MCP server: GNS3 MCP Server
Configuration
All settings come from the environment (prefix GNS3_):
Variable | Default | Purpose |
|
| Controller URL (no |
| – | Login credentials |
| – | Pre-issued bearer token (skips login) |
|
| Verify TLS for https |
| – | Project id used when a tool omits |
|
| Disable all mutating tools (41 read-only tools remain) |
|
|
|
|
| HTTP bind |
|
| Console read timeout (s) |
Install
As a Claude Code plugin
/plugin marketplace add /home/oscar/Code/gns3-mcp
/plugin install gns3The 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_PASSWORDOr 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-mcpSafety
GNS3_READ_ONLY=trueregisters only read-only tools.Destructive tools (
project_delete,node_deletevia flow,controller_shutdown,controller_reload,images_prune) require an explicitconfirm=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 -sArchitecture: 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 toolsacl_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
link_available_filtersB
List packet filters available on a link (delay, drop, corrupt, etc.).
Inputs: link_id (required), project_id. Returns: Generic wrapper for non-object return types.
link_createA
Create a link between two node ports.
Use a node's ports (from node_get/nodes_list) to find adapter_number/port_number.
Inputs: node_a (required), adapter_a (required), port_a (required), node_b (required), +3 more. Returns: object
link_deleteC
Delete a link.
Inputs: link_id (required), project_id. Returns: Generic wrapper for non-object return types.
link_getC
Get full details for a link.
Inputs: link_id (required), project_id. Returns: object
link_resetC
Reset a link (reconnect both ends).
Inputs: link_id (required), project_id. Returns: Generic wrapper for non-object return types.
links_listB
List links in a project (id, endpoints, capture state, filters).
Inputs: project_id, limit. Returns: Generic wrapper for non-object return types.
link_updateC
Update a link: set {"suspend": true} or {"filters": {"delay": [50]}} etc.
Inputs: link_id (required), updates (required), project_id. 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_linksC
List the links attached to a node.
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
Scored across 122 tools
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.
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.
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.
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
Related MCP Connectors
AI network lab: build and validate real multi-vendor router and switch labs from a prompt.
IP intelligence, network diagnostics, and AI service availability tools for AI agents.
Protocol-native energy infrastructure orchestration for AI data centers. Provides 46 MCP tools across 8 grid protocols (IEC-61850, DNP3, Modbus, OCPP, OpenADR, IEEE 2030.5, IEC 60870-5-104, ICCP) with 5 core API primitives: connect, dispatch, settle, comply, and intel. Enables AI agents to programmatically interact with substations, grid interfaces, and energy assets for real-time workload-grid coordination.
Private networking for AI agents: networks, nodes, commands, files, services via hosted MCP.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables 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.4228MIT
- AlicenseAqualityBmaintenanceEnables control of GNS3 network lab automation, including projects, nodes, consoles, and SSH, through Claude Desktop or any MCP-compatible client.15426 PyPI17MIT
- AlicenseAqualityDmaintenanceEnables 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.316Apache 2.0
- AlicenseAqualityCmaintenanceEnables automating GNS3 network labs via the Model Context Protocol, including managing projects, nodes, links, virtual machines, and console commands from ChatGPT.152MIT