Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
GNS3_HOSTYesGNS3 server IP/hostname
GNS3_PORTYesGNS3 server port80
GNS3_USERYesGNS3 username
HTTP_PORTNoMCP server port for HTTP mode8000
LOG_LEVELNoLogging levelINFO
MCP_API_KEYNoAPI key for HTTP mode authentication
GNS3_PASSWORDYesGNS3 password
GNS3_USE_HTTPSNoUse HTTPS for GNS3false
GNS3_VERIFY_SSLNoVerify SSL certstrue

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. Call project(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 for started; the device OS needs more time before its console or SSH answers.

  • Console first access. The first console batch for a node never accessed may contain only read operations; 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 console operation reopens it and keeps the read-first state; that result has a warnings entry. CONSOLE_DISCONNECTED means reopening failed.

  • Trust what results say. unapplied_properties (create) or Warning: not applied by GNS3 (set) means GNS3 ignored those keys for that node type. Error details carry 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

project

list, open, create (auto-opens), close, delete (dry run unless confirm=True)

node

list, create (from template), delete, set (properties; state_action start/stop/suspend/reload/restart)

link

list, batch of connect / disconnect (all validated before any change)

console

batch of send, send_and_wait, read, keystroke

ssh

batch of configure, command, read, disconnect (Netmiko, via SSH proxy)

node_file

Docker nodes: read, write, configure_network

project_docs

get, update the project README

drawing

list, create, update, delete, batch

export_topology_diagram

SVG/PNG of the canvas

notification

subscribe, read, unsubscribe, status

query_resource

read any resource URI (list below)

gns3_connection

check, retry, reconnect

tftp, http_client

TFTP files and HTTP requests through the SSH proxy

search_tools

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 parallel
  • Hardware params apply on create and set (most need the node stopped). Disk slots: hda boot, hdb second, hdc via properties, hdd fourth.

  • Patterns for set/delete: *, R*, *-Core, R[123], JSON array '["R1","R2"]'. Several nodes return a batch result with succeeded_items / failed_items.

  • delete with a pattern deletes nothing and returns matched_nodes; repeat with confirm=True to delete them. A name or a JSON array of names deletes at once.

  • Switch ports can 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. create waits up to 180 s, then looks for the node and names and places it. A TIMEOUT error means the node may still appear: do not create again; check node(action="list") later and fix name/position with node(action="set").

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 only
  • read modes: diff (new output, default), last_page (25 lines), num_pages + pages, all (whole buffer - use rarely). Grep with pattern, case_insensitive, before / after / context.

  • Check the real prompt with last_page before choosing a wait_pattern (regex).

  • keystroke keys: enter, ctrl_c, ctrl_z, ctrl_d, esc, tab, space, up, down, backspace.

  • raw: True on send skips 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 proxy
  • host is the device's lab IP. proxy (default host) picks a lab proxy for isolated networks: query_resource("proxies://").

  • Options: force: True for a fresh session (after a lab restart), session_timeout; per command expect_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 + limit

Project 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

project(action="list"), then project(action="open", name=...)

Console times out or is silent

node started? read with last_page; boot may still run - wait-only send_and_wait

Console type is vnc/spice

only telnet consoles are supported; change with node(action="set", console_type="telnet") (node stopped)

SSH SSH_DISCONNECTED

configure again with force: True

unapplied_properties

key unknown for that node type - check nodes://<pid>/<nid>

The image '<x>' is missing

upload the image to the GNS3 server first

Link "port in use"

link(action="list"), disconnect the old link in the same batch

Tools fail after GNS3 restart

gns3_connection(action="reconnect")

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

CapabilityDetails
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

NameDescription
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; update_available with the update command when PyPI has a newer release - looked up within 300 ms, omitted otherwise) - retry: Force immediate re-authentication (bypasses exponential backoff) - reconnect: Full reconnect - re-authenticate AND clear all console/SSH/notification sessions. Use after GNS3 server restart, project switch, or when sessions are stale.

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"}

# Force re-authentication only
>>> gns3_connection(action="retry")

# Full reconnect (clears all sessions)
>>> gns3_connection(action="reconnect")
{"success": true, "sessions_cleared": {"console": 3, "notification": true}}
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")

# Subscribe to specific project events
>>> notification(action="subscribe", project_id="abc-123")

# Read new events since last read
>>> notification(action="read")

# Read only node events
>>> notification(action="read", filter_action="node.")

# Read only log errors
>>> notification(action="read", filter_action="log.error")

# Check status
>>> notification(action="status")
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")

# Open existing project
>>> project(action="open", name="My Lab")

# Create new project
>>> project(action="create", name="Production Lab")
>>> project(action="create", name="Test Lab", path="/opt/gns3/projects")

# Close current project
>>> project(action="close")

# Delete a project (dry run first, then confirm)
>>> project(action="delete", name="Test Lab")
>>> project(action="delete", name="Test Lab", confirm=True)
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")

# Create new node
>>> node(action="create", template_name="Alpine Linux", x=100, y=200)
>>> node(action="create", template_name="Cisco IOSv", x=300, y=400, node_name="R1", properties={"ram": 1024})
>>> node(action="create", template_name="Ubuntu Cloud Guest", x=0, y=0, node_name="ops1",
...      ram=12288, cpus=6, adapters=2, hda_disk_image="ops1.qcow2", cdrom_image="seed.iso")

# Delete nodes
>>> node(action="delete", node_name="Router1")
>>> node(action="delete", node_name='["R1", "R2"]')
>>> node(action="delete", node_name="*")                  # lists matches only
>>> node(action="delete", node_name="*", confirm=True)    # deletes every node

# Start all nodes
>>> node(action="set", node_name="*", state_action="start")

# Stop all routers
>>> node(action="set", node_name="Router*", state_action="stop")

# Configure node properties
>>> node(action="set", node_name="R1", x=100, y=200, ram=2048)
>>> node(action="set", node_name="ops1", hda_disk_image="ops1-60G.qcow2", options="-cpu host")
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:

  • Initial device configuration (enabling SSH, creating users)

  • Troubleshooting when SSH is unavailable

  • Devices without SSH support (VPCS, simple switches)

Two-phase execution:

  1. VALIDATE ALL operations (check nodes exist, required params present)

  2. EXECUTE ALL operations (only if all valid, sequential execution)

Each operation supports all parameters from the underlying console tool:

  • "send": Send data to console { "type": "send", "node_name": "R1", "data": "show version\n", "raw": false // optional }

  • "send_and_wait": Send command and wait for pattern { "type": "send_and_wait", "node_name": "R1", "command": "show ip interface brief\n", // optional (v0.49.0: omit for wait-only mode) "wait_pattern": "Router#", // optional "timeout": 30, // optional "raw": false, // optional "handle_pagination": true, // optional (v0.53.4: auto-handle --More--) "pagination_patterns": ["--More--", "---(more)---"], // optional (custom patterns) "pagination_key": " " // optional (default: space, can use "\n" for enter) } Wait-only mode (v0.49.0): Omit "command" to just wait for pattern without sending anything. Useful for monitoring boot sequences or waiting for specific output to appear.

  • "read": Read console output (NOTE: returns empty if nothing sent yet - this is normal) { "type": "read", "node_name": "R1", "mode": "diff", // optional: diff/last_page/num_pages/all "pages": 1, // optional, only with mode="num_pages" "pattern": "error", // optional grep pattern "case_insensitive": true, // optional "invert": false, // optional "before": 0, // optional context lines "after": 0, // optional context lines "context": 0 // optional context lines (overrides before/after) } IMPORTANT: Console buffer may be empty on first read (QEMU nodes don't output until prompted). Use 'send_and_wait' to explicitly send a command and read the response, or send commands first with 'send'.

  • "keystroke": Send special keystroke { "type": "keystroke", "node_name": "R1", "key": "enter" // up/down/enter/ctrl_c/etc }

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"} ... ])

# Same command on multiple nodes:
>>> console(operations=[
...     {"type": "send_and_wait", "node_name": "R1", "command": "show ip int brief\n", "wait_pattern": "#"},
...     {"type": "send_and_wait", "node_name": "R2", "command": "show ip int brief\n", "wait_pattern": "#"},
...     {"type": "send_and_wait", "node_name": "R3", "command": "show ip int brief\n", "wait_pattern": "#"}
... ])

# Mixed operations:
>>> console(operations=[
...     {"type": "send", "node_name": "R1", "data": "\n"},  # Wake console
...     {"type": "read", "node_name": "R1", "mode": "last_page"},  # Check prompt
...     {"type": "send_and_wait", "node_name": "R1", "command": "show version\n", "wait_pattern": "#"},
...     {"type": "keystroke", "node_name": "R1", "key": "ctrl_c"}  # Cancel if needed
... ])
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:

  1. VALIDATE ALL operations (check nodes exist, ports free, adapters valid)

  2. EXECUTE ALL operations (only if all valid - atomic)

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")

# Connect two nodes (batch)
>>> link(action="batch", connections=[{
...     "action": "connect",
...     "node_a": "Router1",
...     "node_b": "Router2",
...     "port_a": 0,
...     "port_b": 0,
...     "adapter_a": 0,
...     "adapter_b": 0
... }])

# Disconnect link (batch)
>>> link(action="batch", connections=[{"action": "disconnect", "link_id": "abc123"}])

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")

# Write file
>>> node_file(action="write", node_name="A-PROXY",
...           file_path="etc/network/interfaces",
...           content="auto eth0\niface eth0 inet dhcp")

# Configure network (recommended)
>>> node_file(action="configure_network", node_name="A-PROXY", interfaces=[{
...     "name": "eth0",
...     "mode": "static",
...     "address": "10.199.0.254",
...     "netmask": "255.255.255.0",
...     "gateway": "10.199.0.1"
... }])
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")

# Update README
>>> project_docs(action="update", content="""
... # HA PowerDNS
... ## IPs
... - B-Rec1: 10.2.0.1/24
... - B-Rec2: 10.2.0.2/24
... """)
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")

# Create rectangle
>>> drawing(action="create", drawing_type="rectangle", x=100, y=100, width=200, height=100)

# Create text label
>>> drawing(action="create", drawing_type="text", x=175, y=140, text="Router1", z=1)

# Update drawing position
>>> drawing(action="update", drawing_id="abc123", x=200, y=200)

# Delete drawing
>>> drawing(action="delete", drawing_id="abc123")

# Create multiple drawings
>>> drawing(action="batch", drawings=[
...     {"drawing_type": "rectangle", "x": 100, "y": 100, "width": 200, "height": 100},
...     {"drawing_type": "text", "x": 175, "y": 140, "text": "Router1", "z": 1}
... ])
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:

  • Use node_name="@" in any operation for local execution on SSH proxy container

  • Mix local and remote operations in same batch

  • Useful for: connectivity tests before device access, ansible playbooks

SSH Proxy Services (v0.3.0):

  • TFTP Server: Available on port 69/udp at /opt/gns3-ssh-proxy/tftp (use tftp tool)

  • HTTP/HTTPS Reverse Proxy: Access device web UIs at http://proxy:8023/http-proxy/:/

  • HTTP Client Tool: Make GET requests to device APIs (use http_client tool)

Two-phase execution prevents partial failures:

  1. VALIDATE ALL operations (check required params, valid types)

  2. EXECUTE ALL operations (only if all valid, sequential execution)

Supported operation types:

  • "configure": Configure SSH session (equivalent to old ssh_configure)

  • "command": Execute command (equivalent to old ssh_command, supports local with "@")

  • "disconnect": Disconnect SSH session

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"} ... ])

# Same command on multiple nodes:
>>> ssh(operations=[
...     {"type": "command", "node_name": "R1", "command": "show ip int brief"},
...     {"type": "command", "node_name": "R2", "command": "show ip int brief"}
... ])

# Configuration commands:
>>> ssh(operations=[{
...     "type": "command",
...     "node_name": "R1",
...     "command": [
...         "interface GigabitEthernet0/0",
...         "ip address 10.1.1.1 255.255.255.0",
...         "no shutdown"
...     ]
... }])

# Local execution - test connectivity before device access:
>>> ssh(operations=[
...     {"type": "command", "node_name": "@", "command": "ping -c 2 10.1.1.1"},
...     {"type": "command", "node_name": "@", "command": "ping -c 2 10.1.1.2"},
...     {"type": "command", "node_name": "R1", "command": "show ip int brief"},
...     {"type": "command", "node_name": "R2", "command": "show ip int brief"}
... ])
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"} ] }

# Upload configuration file
>>> tftp(action="upload", filename="startup-config.txt", content=b"hostname Router1\n...")
{"success": true, "action": "upload", "message": "Uploaded startup-config.txt"}

# Download file
>>> tftp(action="download", filename="config.txt")
{"success": true, "action": "download", "content": "aG9zdG5hbWUgUm91dGVyMQo="}

# Delete file
>>> tftp(action="delete", filename="old-config.txt")
{"success": true, "action": "delete", "message": "Deleted old-config.txt"}

# Check TFTP server status
>>> tftp(action="status")
{
  "success": true,
  "action": "status",
  "tftp_enabled": true,
  "tftp_port": 69,
  "tftp_root": "/opt/gns3-ssh-proxy/tftp",
  "file_count": 5,
  "total_size": 10485760
}
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>:/

Example: http://proxy:8023/http-proxy/10.1.1.1:443/ for HTTPS device

The reverse proxy handles SSL termination and provides persistent access
without needing to make API calls.

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", ...} }

# Check device HTTPS API reachability
>>> http_client(action="status", url="https://10.1.1.2:443", verify_ssl=False)
{
  "success": true,
  "action": "status",
  "reachable": true,
  "status_code": 200
}

# Get JSON API with custom headers
>>> http_client(
...     action="get",
...     url="http://10.1.1.3/api/v1/status",
...     headers={"Authorization": "Bearer token123", "Accept": "application/json"}
... )
{
  "success": true,
  "action": "get",
  "status_code": 200,
  "content": "{\"status\": \"online\", ...}",
  "headers": {"content-type": "application/json"}
}

# Alternative: Use reverse proxy (no tool needed)
# Access: http://proxy:8023/http-proxy/10.1.1.1:443/dashboard
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:

  • project: Project management (open, create, close)

  • node: Node management (create, delete, configure)

  • connection: Network connections and GNS3 server

  • console: Console access to devices

  • ssh: SSH access to devices

  • drawing: Topology visualization

  • resource: Resource query tools

  • docker: Docker-specific operations

  • docs: Documentation management

  • topology: Topology operations

  • management: Management operations

  • device-access: Device access (console/SSH)

  • visualization: Visual elements

  • discovery: Tool discovery

Capabilities:

  • CRUD: Supports create/read/update/delete operations via action parameter

  • batch: Supports batch operations (multiple operations in one call)

  • wildcard: Supports wildcard patterns (, Router, R[123])

  • parallel: Supports parallel execution

  • idempotent: Multiple executions produce same result

Resource Mapping:

  • projects://: project, query_resource

  • projects://{project_id}/topology_report: query_resource

  • nodes://{project_id}/: node, query_resource

  • links://{project_id}/: link, query_resource

  • drawings://{project_id}/: drawing, query_resource

  • sessions://console/: console, query_resource

  • sessions://ssh/: ssh, query_resource

  • diagrams://{project_id}/topology: export_topology_diagram, query_resource

Returns: JSON with matching tools and their metadata

Examples: # Find all CRUD tools >>> search_tools(capability="CRUD")

# Find tools for working with nodes
>>> search_tools(category="node")

# Find tools that work with projects:// resources
>>> search_tools(resource_uri="projects://")

# Find batch operation tools
>>> search_tools(capability="batch")

# Find tools with wildcard support
>>> search_tools(capability="wildcard")

Prompts

Interactive templates invoked by user choice

NameDescription
SSH Setup WorkflowDevice-specific SSH configuration for 6 device types with multi-proxy support
Topology Discovery WorkflowDiscover nodes, links, templates, drawings using resources - includes visual diagram guidance for agents
Troubleshooting WorkflowOSI model-based troubleshooting with README checks, diagnostic tools, log collection
Lab Setup WorkflowCreate complete topologies (star/mesh/linear/ring/ospf/bgp) with nodes, links, IPs, and README documentation
Node Setup WorkflowEnd-to-end node setup: create, configure IP, document in README, establish SSH, connect to network

Resources

Contextual data attached and managed by the client

NameDescription
ProjectsList all GNS3 projects with their statuses and IDs
TemplatesList all available GNS3 device templates (routers, switches, Docker containers, VMs)
Console sessionsList all console sessions (optionally filtered by ?project_id=xxx query parameter)
SSH sessionsList all SSH sessions (optionally filtered by ?project_id=xxx query parameter)
Main proxy statusHealth status and version of the main SSH proxy on GNS3 host (default proxy for ssh_configure)
Lab proxy registryAll discovered SSH proxy containers in GNS3 lab projects - use proxy_id for routing through isolated networks
All proxy sessionsAggregated list of ALL active SSH sessions from main proxy and lab proxies - global lab infrastructure view

TDQS

A3.7/5.0

Scored across 15 tools

Disambiguation4/5

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.

Naming Consistency3/5

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.

Tool Count4/5

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.

Completeness4/5

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.

Maintenance

ActivityNo data
ResponsivenessOutdated data