GNS3 MCP Server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| GNS3_HOST | Yes | GNS3 server IP/hostname | |
| GNS3_PORT | Yes | GNS3 server port | 80 |
| GNS3_USER | Yes | GNS3 username | |
| HTTP_PORT | No | MCP server port for HTTP mode | 8000 |
| LOG_LEVEL | No | Logging level | INFO |
| MCP_API_KEY | No | API key for HTTP mode authentication | |
| GNS3_PASSWORD | Yes | GNS3 password | |
| GNS3_USE_HTTPS | No | Use HTTPS for GNS3 | false |
| GNS3_VERIFY_SSL | No | Verify SSL certs | true |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
GNS3 MCP Server
Automation for GNS3 v3 network labs: projects, nodes, links, device consoles (telnet), SSH through a proxy, drawings, notifications and topology export.
Rules
Use these tools only. The GNS3 API needs JWT auth that the server handles; never call it with curl or httpx.
Current project. Node, link, console and drawing tools act on the server's current project. GNS3 can have several projects open; after a server restart the first opened one is picked. A project you opened stays current until you open another one, or close or delete it;
gns3_connection(action="check")shows it. Callproject(action="open", name=...)when in doubt.Read before you change.
project_docs(action="get")keeps the lab's IP plan and credentials;query_resource("projects://<id>/topology_report")shows nodes, links and status in one call.Nodes boot slowly.
node(action="set", state_action="start")waits up to ~60 s forstarted; the device OS needs more time before its console or SSH answers.Console first access. The first
consolebatch for a node never accessed may contain onlyreadoperations; other operations are skipped. Read once, then send.Dropped consoles reopen by themselves. If a node's console connection closed (node restart, network reset), the next
consoleoperation reopens it and keeps the read-first state; that result has awarningsentry.CONSOLE_DISCONNECTEDmeans reopening failed.Trust what results say.
unapplied_properties(create) orWarning: not applied by GNS3(set) means GNS3 ignored those keys for that node type. Errordetailscarry GNS3's reason (missing image, connected switch, node must be stopped).Record what you build with
project_docs(action="update", content=...).
Tools
Tool | Actions / operations |
|
|
|
|
|
|
| batch of |
| batch of |
| Docker nodes: |
|
|
|
|
| SVG/PNG of the canvas |
|
|
| read any resource URI (list below) |
|
|
| TFTP files and HTTP requests through the SSH proxy |
| find tools by category or capability |
Nodes
node(action="create", template_name="Cisco IOSv", node_name="R1", x=0, y=0)
node(action="create", template_name="Ubuntu Cloud Guest", node_name="ops1", x=200, y=0,
ram=8192, cpus=4, adapters=2, hda_disk_image="ops1-60G.qcow2",
cdrom_image="seed.iso", options="-cpu host")
node(action="set", node_name="ops1", properties={"adapter_type": "virtio-net-pci"})
node(action="set", node_name="*", state_action="start") # all nodes, in parallelHardware params apply on
createandset(most need the node stopped). Disk slots:hdaboot,hdbsecond,hdcviaproperties,hddfourth.Patterns for
set/delete:*,R*,*-Core,R[123], JSON array'["R1","R2"]'. Several nodes return a batch result withsucceeded_items/failed_items.deletewith a pattern deletes nothing and returnsmatched_nodes; repeat withconfirm=Trueto delete them. A name or a JSON array of names deletes at once.Switch
portscan change only while no links are attached.First use of a template with big disk images (Windows, multi-GB qcow2) can keep GNS3 busy for minutes.
createwaits up to 180 s, then looks for the node and names and places it. ATIMEOUTerror means the node may still appear: do not create again; checknode(action="list")later and fix name/position withnode(action="set").
Links
link(action="batch", connections=[
{"action": "connect", "node_a": "R1", "adapter_a": "GigabitEthernet0/0", "port_a": 0,
"node_b": "SW1", "adapter_b": "Ethernet2", "port_b": 0},
{"action": "disconnect", "link_id": "<id from link list>"},
])A port name in adapter_* fixes adapter and port (port_* ignored); with numbers the link uses (adapter_*, port_*) - switches keep all ports on adapter 0. Names are case-sensitive.
Console
console(operations=[{"type": "read", "node_name": "R1", "mode": "last_page"}]) # first access
console(operations=[
{"type": "send", "node_name": "R1", "data": "\n"},
{"type": "send_and_wait", "node_name": "R1", "command": "show ip route\n",
"wait_pattern": "R1#", "timeout": 30, "handle_pagination": True},
])
console(operations=[{"type": "send_and_wait", "node_name": "R1",
"wait_pattern": "login:", "timeout": 180}]) # no command = wait onlyreadmodes:diff(new output, default),last_page(25 lines),num_pages+pages,all(whole buffer - use rarely). Grep withpattern,case_insensitive,before/after/context.Check the real prompt with
last_pagebefore choosing await_pattern(regex).keystrokekeys:enter,ctrl_c,ctrl_z,ctrl_d,esc,tab,space,up,down,backspace.raw: Trueonsendskips escape processing (e.g. MikroTik). Keep pasted lines short on FortiOS and older IOS.Sessions close after 30 min idle; buffers keep all output (10 MB cap).
SSH
Enable SSH on the device through the console first, then:
ssh(operations=[
{"type": "configure", "node_name": "R1", "device_dict": {
"device_type": "cisco_ios", "host": "10.1.0.1", "username": "admin", "password": "..."}},
{"type": "command", "node_name": "R1", "command": "show version"},
{"type": "command", "node_name": "R1", "command": ["interface Gi0/1", "no shutdown"]},
])
ssh(operations=[{"type": "command", "node_name": "@", "command": "ping -c 2 10.1.0.1"}]) # on the proxyhostis the device's lab IP.proxy(defaulthost) picks a lab proxy for isolated networks:query_resource("proxies://").Options:
force: Truefor a fresh session (after a lab restart),session_timeout; per commandexpect_string,read_timeout,wait_timeout(long jobs report progress).Sessions expire after 30 min idle and are recreated on the next
configure.
Notifications
notification(action="subscribe", project_id="<id>") # omit project_id for controller events
notification(action="read", filter_action="node.updated") # modes: diff (default), all, last + limitProject events: node.*, link.*, drawing.*, snapshot.restored, ping. Controller events: compute.*, project.*, template.*, log.error|warning|info, ping (CPU/memory). One subscription at a time; buffer keeps 5000 events.
Resources (query_resource)
projects://, projects://<id>, projects://<id>/readme, projects://<id>/topology_report, nodes://<pid>/, nodes://<pid>/<nid>, nodes://<pid>/<nid>/template, links://<pid>/, drawings://<pid>/, templates://, templates://<tid>, sessions://console/, sessions://ssh/, sessions://ssh/<node>/history, sessions://ssh/<node>/buffer, proxies:///status, proxies://, diagrams://<pid>/topology.
Connection
The server starts without waiting for GNS3 and authenticates in the background (retry 5 s -> 300 s). gns3_connection(action="check") shows the state and last error, the current project and the server version; when PyPI has a newer gns3-mcp it adds update_available with the update command - tell the user. retry re-authenticates now, reconnect also clears console/SSH/notification sessions (use after a GNS3 restart; a single dropped console needs no reconnect).
Troubleshooting
Symptom | Do this |
"No project opened" / wrong project |
|
Console times out or is silent | node |
Console type is vnc/spice | only telnet consoles are supported; change with |
SSH |
|
| key unknown for that node type - check |
| upload the image to the GNS3 server first |
Link "port in use" |
|
Tools fail after GNS3 restart |
|
Guided workflows are available as prompts: "Node Setup Workflow", "Lab Setup Workflow", "SSH Setup Workflow", "Topology Discovery Workflow", "Troubleshooting Workflow".
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| extensions | {
"io.modelcontextprotocol/ui": {}
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| gns3_connectionA | Manage GNS3 server connection CRUD-style connection management tool. Actions:
- check: Check connection status (connection state, error details, last attempt time,
current project, server version; Args: action: Connection action to perform Returns: JSON with connection status or reconnection result Examples: # Check connection status >>> gns3_connection(action="check") {"connected": false, "server": "http://192.168.1.20:80", "error": "Connection timeout", "last_attempt": "08:15:42 30.10.2025"} |
| notificationA | Subscribe to GNS3 server event notifications and read buffered events. GNS3 streams real-time events: node state changes, link updates, log messages, etc. This tool subscribes to the stream in background and buffers events for on-demand reading. Actions: - subscribe: Start listening to notification stream (controller or project-level) - read: Read buffered events (supports diff/all/last modes with optional action filter) - unsubscribe: Stop listening and clear buffer - status: Check subscription status and buffer stats Event types (action field): Controller: compute., project., template.*, log.error, log.warning, log.info, ping Project: node.created/updated/deleted, link.created/updated/deleted, drawing.created/updated/deleted, snapshot.restored, ping Examples: # Subscribe to all events >>> notification(action="subscribe") |
| projectA | Manage GNS3 projects CRUD-style project management tool. Actions: - list: List all projects - open: Open a project by name - create: Create a new project and auto-open it - close: Close the currently opened project - delete: Delete a project by exact name with all its nodes, disks and files (WARNING: cannot be undone). Without confirm=True it is a dry run that deletes nothing and returns the project's id, status and path Args: action: Project action to perform name: Project name (required for open/create/delete) path: Optional project directory path (create only) format: Output format for 'list' action confirm: Required (True) for 'delete' to actually delete Returns: JSON with ProjectInfo for created project, or list of projects Examples: # List all projects >>> project(action="list") >>> project(action="list", format="json") |
| nodeA | Manage GNS3 nodes (CRUD operations) v0.47.0: CRUD-style consolidation of create_node, delete_node, and set_node. v0.40.0: Enhanced with wildcard and bulk operation support. Actions: - list: List nodes in a project - create: Create new node from template at specified coordinates - delete: Delete node(s) from project (WARNING: destructive, cannot be undone) - set: Configure node properties and/or control state (supports wildcards/bulk) Wildcard Patterns (for 'set' and 'delete'): - Single node: "Router1" - All nodes: "" - Prefix match: "Router" (matches Router1, Router2, RouterCore) - Suffix match: "*-Core" (matches Router-Core, Switch-Core) - Character class: "R[123]" (matches R1, R2, R3) - JSON array: '["Router1", "Router2", "Switch1"]' Delete safety: - A pattern delete without confirm=True deletes nothing and returns 'matched_nodes' (dry run); repeat with confirm=True to delete them - A single name or a JSON array of names deletes at once - Several nodes return a BatchOperationResult; names not in the project are skipped Validation Rules: - name parameter requires node to be stopped - Hardware properties (ram, cpus, adapters, hd*_disk_image, cdrom_image, options) apply to both 'create' and 'set'; disk/cdrom/options are QEMU-only - Disk slots: hda = boot disk, hdb = 2nd, hdc = 3rd (via properties), hdd = 4th - Values GNS3 did not apply are reported ('unapplied_properties' / warning) - never silent - For IOU nodes, 'adapters' maps to 'ethernet_adapters' automatically - ports parameter applies to ethernet_switch nodes only - state_action values: start, stop, suspend, reload, restart Returns: Single node: Status message Multiple nodes: BatchOperationResult JSON with per-node success/failure Examples: # List nodes in project >>> node(action="list", project_id="abc-123") >>> node(action="list", project_id="abc-123", format="json") |
| consoleA | Execute console operations (BATCH-ONLY) v0.47.0: Batch-only console tool. Individual console tools removed (aggressive consolidation). IMPORTANT: Prefer SSH tools when available! Console tools are primarily for:
Two-phase execution:
Each operation supports all parameters from the underlying console tool:
Args: operations: List of operation dictionaries (see examples above) Returns: JSON with execution results: { "completed": [0, 1, 2], // Indices of successful operations "failed": [3], // Indices of failed operations "results": [ { "operation_index": 0, "success": true, "operation_type": "send_and_wait", "node_name": "R1", "result": {...} // Operation-specific result }, ... ], "total_operations": 4, "execution_time": 5.3 } Examples: # Multiple commands on one node: >>> console(operations=[ ... {"type": "send_and_wait", "node_name": "R1", "command": "show version\n", "wait_pattern": "Router#"}, ... {"type": "send_and_wait", "node_name": "R1", "command": "show ip route\n", "wait_pattern": "Router#"}, ... {"type": "read", "node_name": "R1", "mode": "diff"} ... ]) |
| linkA | Manage network connections (links) v0.47.0: Renamed from set_network_connections to link (CRUD consolidation). Actions: - list: List all links in a project - batch: Execute multiple connect/disconnect operations with two-phase validation Two-phase execution for batch operations prevents partial topology changes:
Connection Operations (for 'batch' action): Connect: {action: "connect", node_a, node_b, port_a, port_b, adapter_a, adapter_b} Disconnect: {action: "disconnect", link_id} Port addressing: - adapter_* as number: link uses (adapter_*, port_*). Switches/hubs have all ports on adapter 0, so port_b=2 selects Ethernet2. - adapter_* as port name ("eth1", "Ethernet2", "Gi0/1"): the name fixes both adapter and port; port_* is ignored. Examples: # List links >>> link(action="list", project_id="abc-123") >>> link(action="list", project_id="abc-123", format="json") Returns: JSON with OperationResult (completed and failed operations) or list of links |
| node_fileA | Manage Docker node files (CRUD operations) v0.47.0: CRUD-style consolidation of get_node_file, write_node_file, and configure_node_network. Actions: - read: Read file from Docker node filesystem - write: Write file to Docker node filesystem (WARNING: does NOT restart node) - configure_network: Configure network interfaces (full workflow: write + restart) IMPORTANT: Use 'configure_network' for network configuration as it handles the complete workflow (write config → restart node → apply changes). Returns: JSON with file contents, confirmation message, or configured interfaces Examples: # Read file >>> node_file(action="read", node_name="A-PROXY", file_path="etc/network/interfaces") |
| project_docsA | Manage project documentation (CRUD operations) v0.47.0: CRUD-style consolidation of get_project_readme and update_project_readme. Actions: - get: Read project README/notes (markdown format) - update: Write project README/notes Project documentation typically includes: - IP addressing schemes and VLANs - Node credentials (usernames, password vault keys) - Architecture diagrams (text-based) - Configuration templates and snippets - Troubleshooting notes and runbooks Returns: JSON with project_id and markdown content, or for 'update' a confirmation with content_length (sent), previous_length and stored_length (read back after the write; a 'warning' is added if the stored text differs from what was sent) Examples: # Get README >>> project_docs(action="get") >>> project_docs(action="get", project_id="a920c77d-6e9b-41b8-9311-b4b866a2fbb0") |
| export_topology_diagramA | Export topology diagram to SVG/PNG files on disk. For agents: use diagrams://{project_id}/topology resource for direct access without saving files. |
| drawingA | Manage drawings (CRUD operations) v0.47.0: CRUD-style consolidation of create_drawing, update_drawing, delete_drawing, and create_drawings_batch. Actions: - list: List all drawings in a project - create: Create new drawing (rectangle, ellipse, line, text) - update: Update existing drawing properties - delete: Delete drawing (WARNING: destructive, cannot be undone) - batch: Create multiple drawings with two-phase validation Returns: JSON with drawing info or batch operation results Examples: # List drawings >>> drawing(action="list", project_id="abc-123") >>> drawing(action="list", project_id="abc-123", format="json") |
| sshA | Execute SSH operations (BATCH-ONLY) v0.47.0: Batch-only SSH tool. Individual SSH tools removed (aggressive consolidation). v0.28.0: Local execution support with node_name="@" Local Execution Support:
SSH Proxy Services (v0.3.0):
Two-phase execution prevents partial failures:
Supported operation types:
Args: operations: List of operation dicts, each with: - type (str): Operation type (required) - node_name (str): Node name (or "@" for local execution) (required) - Additional params specific to operation type Returns: JSON with execution results including completed/failed indices Examples: # Configure session + run commands: >>> ssh(operations=[ ... {"type": "configure", "node_name": "R1", "device_dict": { ... "device_type": "cisco_ios", "host": "10.1.0.1", ... "username": "admin", "password": "cisco123" ... }}, ... {"type": "command", "node_name": "R1", "command": "show version"}, ... {"type": "command", "node_name": "R1", "command": "show ip route"} ... ]) |
| tftpA | Manage TFTP server files (CRUD-style) v0.3.0: TFTP server integration for device firmware/config file serving TFTP server runs on SSH proxy (port 69/udp) with root directory /opt/gns3-ssh-proxy/tftp. Provides read-write access for devices to upload/download files. Actions: - list: List all files in TFTP root directory - upload: Upload file to TFTP server (requires filename and content) - download: Download file from TFTP server (requires filename) - delete: Delete file from TFTP server (requires filename) - status: Check TFTP server status File Content Handling: - Upload: Provide raw bytes in content parameter (base64 encoded automatically) - Download: Returns file content as base64 encoded string Returns: JSON response with success status, action, and results Examples: # List TFTP files >>> tftp(action="list") { "success": true, "action": "list", "files": [ {"filename": "config.txt", "size": 1024, "modified": "2025-01-15 10:30:00"}, {"filename": "firmware.bin", "size": 5242880, "modified": "2025-01-14 09:15:00"} ] } |
| http_clientA | HTTP/HTTPS client for lab device web interfaces (CRUD-style) v0.3.0: HTTP client integration for accessing device APIs and web UIs Reverse HTTP/HTTPS proxy available at http://proxy:8023/http-proxy/<device_ip>:/ for external device web UI access without SSH tunnel. Actions: - get: Send HTTP GET request to device and return response - status: Check if device web interface is reachable (HEAD request) SSL Certificate Handling: - verify_ssl=False (default): Ignore self-signed certificates - verify_ssl=True: Verify SSL certificates (may fail for lab devices) Reverse Proxy Alternative: Instead of using this tool, you can also access device web UIs through the reverse proxy at http://proxy:8023/http-proxy/<device_ip>:/ Returns: JSON response with success status, action, and results Examples: # Get device web interface >>> http_client(action="get", url="http://10.1.1.1") { "success": true, "action": "get", "status_code": 200, "content": "...", "headers": {"content-type": "text/html", ...} } |
| query_resourceC | Universal resource query tool - access any GNS3 MCP resource. See tool implementation docstring for comprehensive URI pattern documentation. |
| search_toolsA | Discover GNS3 MCP tools (v0.47.0 - Tool Discovery) Search and filter available tools by category, capability, or resource URI. Returns tool metadata including description, actions, and applicable resources. Categories:
Capabilities:
Resource Mapping:
Returns: JSON with matching tools and their metadata Examples: # Find all CRUD tools >>> search_tools(capability="CRUD") |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| SSH Setup Workflow | Device-specific SSH configuration for 6 device types with multi-proxy support |
| Topology Discovery Workflow | Discover nodes, links, templates, drawings using resources - includes visual diagram guidance for agents |
| Troubleshooting Workflow | OSI model-based troubleshooting with README checks, diagnostic tools, log collection |
| Lab Setup Workflow | Create complete topologies (star/mesh/linear/ring/ospf/bgp) with nodes, links, IPs, and README documentation |
| Node Setup Workflow | End-to-end node setup: create, configure IP, document in README, establish SSH, connect to network |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| Projects | List all GNS3 projects with their statuses and IDs |
| Templates | List all available GNS3 device templates (routers, switches, Docker containers, VMs) |
| Console sessions | List all console sessions (optionally filtered by ?project_id=xxx query parameter) |
| SSH sessions | List all SSH sessions (optionally filtered by ?project_id=xxx query parameter) |
| Main proxy status | Health status and version of the main SSH proxy on GNS3 host (default proxy for ssh_configure) |
| Lab proxy registry | All discovered SSH proxy containers in GNS3 lab projects - use proxy_id for routing through isolated networks |
| All proxy sessions | Aggregated list of ALL active SSH sessions from main proxy and lab proxies - global lab infrastructure view |
TDQS
Scored across 15 tools
Most tools map cleanly to a single resource (project, node, link, drawing, tftp, project_docs) with distinct action sets. The main overlap is ssh vs console (both device access, though the console description explicitly says to prefer SSH) and query_resource, a catch-all that can read the same data as the list actions of node/link/project. These boundaries are documented well enough that an agent can pick correctly, but they are not perfectly disjoint.
The dominant pattern is consolidated noun tools with an 'action' parameter (node, project, link, drawing, tftp, ssh, console, notification), which is coherent. However, several tools break that pattern with verb_noun names (export_topology_diagram, query_resource, search_tools) and others use compound noun names (gns3_connection, node_file, project_docs, http_client). It is readable but mixes two conventions rather than following one predictable scheme.
Fifteen tools for a lab-automation server covering projects, topology, device access, files, and discovery is well within a reasonable range. The v0.47.0 batch/CRUD consolidation (e.g. separate ssh_configure/ssh_command folded into ssh, create/delete/set folded into node) keeps the surface lean rather than sprawling.
The surface covers the full lab lifecycle: project CRUD, node CRUD plus state control, link connect/disconnect, drawings, docs, file I/O, TFTP, notifications, connection recovery, topology export, and a universal resource query backstop. Notable gaps are snapshots (referenced only as an event type) and template management — node create takes a template_name but there is no action to list or inspect templates — which an agent must work around.