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

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.