Skip to main content
Glama

GNS3 MCP Server

Model Context Protocol (MCP) server for GNS3 network lab automation. Control GNS3 projects, nodes, and device consoles through Claude Desktop or any MCP-compatible client.

PyPI · Requires GNS3 server v3.x (v3 API) · Install page · CHANGELOG.md

Features

  • One-command setup: uvx gns3-mcp configure <agent> for Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Cline, Kiro, OpenCode, Codex and Gemini CLI - or ask your agent to install it from the install page

  • Claude plugin: one install for Claude Code and Cowork - the server plus a skill with lab workflows

  • 15 Tools: CRUD-style tools with an action parameter (project(action="open"), node(action="create"), ...)

  • 25 Resources: Read-only data (projects, nodes, links, templates, sessions, proxies, topology report)

  • 5 Prompts: Guided workflows (SSH setup, topology discovery, troubleshooting, lab setup, node setup)

  • Node Control: Create from templates, start/stop/restart with wildcards (*, Router*, R[123], JSON arrays) and parallel execution

  • Node Hardware: RAM, CPUs, adapters, QEMU disks (hda/hdb/hdd), CD-ROM image, QEMU options (e.g. -cpu host) on create and set; values GNS3 did not apply are reported back

  • Console Access: Batch telnet automation with pattern waits, wait-only mode, pagination handling, grep filtering

  • SSH Automation: Network device automation via Netmiko (200+ device types) through the SSH proxy

  • Network Topology: Batch connect/disconnect links with two-phase validation, drawings, SVG/PNG export

  • Notifications: Live GNS3 event stream (node/link/drawing changes, logs, compute events)

  • Docker Nodes: Configure container networks, read/write files

  • Lab Services: TFTP server and HTTP client/reverse proxy via the SSH proxy container

  • Tool Discovery: search_tools() with category/capability/resource filtering; query_resource() reads any resource from clients without resource support

  • Security: required API key on every HTTP/SSE entry point (/health open for probes), service privilege isolation, HTTPS to GNS3

Related MCP server: MCP Packet Tracer

Installation

Needs a GNS3 3.x server and uv. Step-by-step page: https://chistokhinsv.github.io/gns3-mcp

Let your agent install it

Paste this into Claude Code, Codex, Cursor or any agent that can run commands:

Install the GNS3 MCP server from https://chistokhinsv.github.io/gns3-mcp

The agent follows the install steps for agents, asks you for the GNS3 server details and runs configure. You can type the password into your own terminal instead of giving it to the agent.

Or run one command yourself

uvx gns3-mcp@latest configure claude

Use your agent's name: claude (Claude Code), claude-desktop, cursor, vscode (GitHub Copilot), windsurf (Devin Desktop), cline, kiro, opencode, codex or gemini. Without a name it shows a numbered list; 99 (manual) is for any other agent: it saves the settings and prints the setup guide. The command:

  • asks for the GNS3 host, port, user and password and checks the login;

  • saves them in ~/.gns3-mcp/.env, so agent configs hold no passwords;

  • adds the gns3 server to the agent's MCP config (other servers stay; a backup of each file is kept);

  • adds a short instructions file or block to the agent's rules, telling it to use the GNS3 tools;

  • asks last whether to update automatically (default yes): the agent then runs uvx gns3-mcp@latest, which picks up a new release at each start but needs internet to start. Answer no for offline labs: the config pins the version that ran configure (gns3-mcp@<version>).

Restart the agent afterwards and ask it to list your GNS3 projects. Running it again updates the same entries.

Agent not listed, or you prefer to edit the config yourself? This prints the ready-made config and instructions for every agent, with the file paths for your computer:

uvx gns3-mcp@latest configure --instructions

Option

Effect

--project

write the project's config files in the current folder instead of the user-wide config

--dry-run

show what would change, write nothing

--yes

no prompts: --host, --port, --user, and GNS3_PASSWORD from the environment

--no-instructions

leave the agent's rules alone

--auto-update / --no-auto-update

run gns3-mcp@latest (default) or pin this version; the choice is saved and kept by later runs

Updating

gns3_connection(action="check") tells the agent when PyPI has a newer release (update_available, with the command for your install). The lookup waits at most 300 ms and stays silent on a slow or broken network; GNS3_MCP_UPDATE_CHECK=false turns it off.

Installed with

Update

configure, auto-update on

restart the agent

configure, pinned

uvx gns3-mcp@latest configure <agent> --yes, then restart the agent

Claude plugin

claude plugin update gns3-lab@gns3-mcp (or turn on auto-update for the marketplace in /plugin > Marketplaces)

.mcpb extension

install the new .mcpb from the releases

Docker

docker compose pull && docker compose up -d

Run configure as gns3-mcp@latest: a plain uvx gns3-mcp ... keeps using the version uvx cached on its first run.

Other ways

You use

Install

Platforms

Claude Code or Cowork, with the lab skill

Claude plugin

Windows, macOS, Linux (needs uv)

Claude Desktop, without a terminal

.mcpb extension - double-click

Windows, macOS

Your own config files or pip install

Manual setup

Windows, macOS, Linux

A shared HTTP server

Docker or the Windows service

any

Claude plugin (Claude Code and Cowork)

The plugin installs the gns3 MCP server (started locally with uv run --locked; plugin/uv.lock pins the server and every dependency by hash) together with the gns3-lab-automation skill, which teaches Claude the lab workflows. Requires uv on PATH.

# In Claude Code in a terminal
/plugin marketplace add ChistokhinSV/gns3-mcp
/plugin install gns3-lab@gns3-mcp
  • Claude Code in the desktop app: /plugin ... there only opens the plugin browser, which lists plugins from marketplaces you have already added. Run this once in a terminal (the desktop app reads the same settings); it adds the marketplace and installs the plugin:

    claude plugin install gns3-lab --marketplace ChistokhinSV/gns3-mcp
  • Claude Code asks for GNS3 host, port, username and password when the plugin is enabled (the password goes to the system credential store).

  • Cowork (desktop app): Customize > Plugins > Add > Add marketplace → ChistokhinSV/gns3-mcp, add GNS3 Lab. Cowork does not ask for settings, so put them in ~/.gns3-mcp/.env:

    GNS3_HOST=192.168.1.20
    GNS3_PORT=80
    GNS3_USER=admin
    GNS3_PASSWORD=your-password
  • Chat on claude.ai doesn't start local servers - on Claude Desktop use the .mcpb below.

Empty plugin settings fall back to environment variables, then ./.env, then ~/.gns3-mcp/.env (or GNS3_MCP_ENV_FILE). Details: plugin/README.md.

Skill only: skill-plugin/ (GNS3 Lab Guide) is the same skill without the server. It is the version for Anthropic's plugin directory, which takes no local MCP server from community publishers. With it, set the server up once with uvx gns3-mcp configure claude, then claude plugin install gns3-lab-guide --marketplace ChistokhinSV/gns3-mcp. Install one of the two plugins, not both (the skill would load twice).

Claude Desktop (.mcpb)

The .mcpb is an MCP Bundle (manifest 0.4, uv runtime): it holds only the source, and Claude Desktop installs the Python dependencies with its own uv on first start (allow ~30 s). Windows and macOS.

  1. Download mcp-server.mcpb from Releases, or build it: just build (creates mcp-server\mcp-server.mcpb)

  2. Install: double-click it, drag it into Claude Desktop, or Settings > Extensions > Advanced settings > Install Extension…

  3. Enter credentials when the installer asks: GNS3 host, GNS3 port, username, password. Change them later in Settings > Extensions > GNS3 Lab Controller. The password is passed to the server as an environment variable, never on the command line.

  4. Check logs if issues occur:

    Windows: %APPDATA%\Claude\logs\mcp-server-GNS3 Lab Controller.log
    macOS:   ~/Library/Logs/Claude/mcp-server-GNS3 Lab Controller.log

The Claude directory no longer lists .mcpb extensions; install from the file. For Claude Code and Cowork use the plugin instead.

Tools

Tool

Actions / purpose

gns3_connection

check, retry, reconnect

project

list, open, create, close, delete (needs confirm=True)

node

list, create, delete (pattern deletes need confirm=True), set (properties and start/stop/suspend/reload/restart)

link

list, batch (connect / disconnect)

drawing

list, create, update, delete, batch

console

batch of send, send_and_wait, read, keystroke

ssh

batch of configure, command, read, disconnect

node_file

read, write, configure_network (Docker nodes)

project_docs

get, update (per-project README / notes)

notification

subscribe, read, unsubscribe, status

tftp, http_client

SSH proxy lab services

query_resource, search_tools, export_topology_diagram

resource access, tool discovery, diagram export

Example

# Ubuntu VM with a bigger boot disk, cloud-init ISO and host CPU model
node(action="create", template_name="Ubuntu Cloud Guest", node_name="ops1", x=0, y=0,
     ram=8192, cpus=4, adapters=2, hda_disk_image="ops1-60G.qcow2",
     cdrom_image="ops1-seed.iso", options="-cpu host")

# Wire it to switch port Ethernet2, start it, wait for the login prompt
link(action="batch", connections=[{"action": "connect", "node_a": "ops1", "adapter_a": "eth0",
     "port_a": 0, "node_b": "SW1", "adapter_b": "Ethernet2", "port_b": 0}])
node(action="set", node_name="ops1", state_action="start")
console(operations=[{"type": "read", "node_name": "ops1"}])  # first access: read only
console(operations=[{"type": "send_and_wait", "node_name": "ops1",
                     "wait_pattern": "login:", "timeout": 180}])  # wait-only, sends nothing

Manual setup

uvx gns3-mcp configure --instructions prints these steps with the paths for your computer. The sections below show them per client.

Claude Code without the plugin

Prerequisites:

  • GNS3 server running and accessible

  • Claude Code installed

  • uv package manager (for uvx): Install with pip install uv or download from https://github.com/astral-sh/uv

Option 1: Using uvx (Recommended - Faster)

# Single command - no .env file needed!
claude mcp add --transport stdio gns3-mcp `
  --env GNS3_HOST=192.168.1.20 `
  --env GNS3_PORT=80 `
  --env GNS3_USER=admin `
  --env GNS3_PASSWORD=your-password `
  --scope user `
  -- uvx gns3-mcp@latest

# Verify installation
claude mcp get gns3-mcp
# Should show: Status: ✓ Connected

Option 2: Using pip (Traditional)

# Step 1: Install package
pip install gns3-mcp

# Step 2: Add to Claude Code with credentials
claude mcp add --transport stdio gns3-mcp `
  --env GNS3_HOST=192.168.1.20 `
  --env GNS3_PORT=80 `
  --env GNS3_USER=admin `
  --env GNS3_PASSWORD=your-password `
  --scope user `
  -- gns3-mcp

# Step 3: Verify installation
claude mcp get gns3-mcp
# Should show: Status: ✓ Connected

Why uvx? 10-100× faster than pip, automatic dependency isolation, no venv management needed.


Installation by Editor

Claude Code Setup

STDIO Mode (Recommended)

STDIO mode is more secure - no HTTP service, no authentication needed, runs only when Claude Code is active.

Using uvx (Recommended):

# 1. Install uv (one-time setup)
pip install uv

# 2. Create .env file
@"
GNS3_HOST=192.168.1.20
GNS3_PORT=80
GNS3_USER=admin
GNS3_PASSWORD=your-password
"@ | Out-File -FilePath .env -Encoding ASCII

# 3. Add to Claude Code
claude mcp add --transport stdio gns3-mcp --scope user -- uvx gns3-mcp@latest

# 4. Verify
claude mcp get gns3-mcp

Using pip:

# 1. Install package globally
pip install gns3-mcp

# 2. Create .env file in project directory
@"
GNS3_HOST=192.168.1.20
GNS3_PORT=80
GNS3_USER=admin
GNS3_PASSWORD=your-password
"@ | Out-File -FilePath .env -Encoding ASCII

# 3. Add to Claude Code
claude mcp add --transport stdio gns3-mcp --scope user -- gns3-mcp

# 4. Verify
claude mcp get gns3-mcp
# Should show: Status: ✓ Connected

Environment Variables:

Variable

Required

Description

Example

GNS3_HOST

Yes

GNS3 server IP/hostname

192.168.1.20

GNS3_PORT

Yes

GNS3 server port

80 or 3080

GNS3_USER

Yes

GNS3 username

admin

GNS3_PASSWORD

Yes

GNS3 password

your-password

Cursor Setup

Configuration File Location:

  • Project-specific: .cursor\mcp.json (in project directory)

  • Global: %USERPROFILE%\.cursor\mcp.json

Using uvx (Recommended):

  1. Install uv: pip install uv

  2. Create/edit .cursor\mcp.json:

{
  "mcpServers": {
    "gns3-mcp": {
      "command": "uvx",
      "args": ["gns3-mcp@latest"],
      "env": {
        "GNS3_HOST": "192.168.1.20",
        "GNS3_PORT": "80",
        "GNS3_USER": "admin",
        "GNS3_PASSWORD": "your-password"
      }
    }
  }
}

Using pip:

  1. Install package: pip install gns3-mcp

  2. Create/edit .cursor\mcp.json:

{
  "mcpServers": {
    "gns3-mcp": {
      "command": "gns3-mcp",
      "args": [],
      "env": {
        "GNS3_HOST": "192.168.1.20",
        "GNS3_PORT": "80",
        "GNS3_USER": "admin",
        "GNS3_PASSWORD": "your-password"
      }
    }
  }
}
  1. Restart Cursor


Windsurf Setup

Configuration File Location: %USERPROFILE%\.codeium\windsurf\mcp_config.json

Using uvx (Recommended):

  1. Install uv: pip install uv

  2. Create/edit mcp_config.json:

{
  "mcpServers": {
    "gns3-mcp": {
      "command": "uvx",
      "args": ["gns3-mcp@latest"],
      "env": {
        "GNS3_HOST": "192.168.1.20",
        "GNS3_PORT": "80",
        "GNS3_USER": "admin",
        "GNS3_PASSWORD": "your-password"
      }
    }
  }
}

Using pip:

  1. Install package: pip install gns3-mcp

  2. Create/edit mcp_config.json:

{
  "mcpServers": {
    "gns3-mcp": {
      "command": "gns3-mcp",
      "args": [],
      "env": {
        "GNS3_HOST": "192.168.1.20",
        "GNS3_PORT": "80",
        "GNS3_USER": "admin",
        "GNS3_PASSWORD": "your-password"
      }
    }
  }
}
  1. Restart Windsurf

Note: Cursor and Windsurf use identical configuration formats.


Troubleshooting

Connection Issues:

# Test GNS3 server connectivity (no auth needed for this endpoint)
curl http://192.168.1.20:80/v3/version

# Check Claude Code MCP status
claude mcp get gns3-mcp

# View detailed logs (Claude Code)
# Check console output when running commands

Common Issues:

  • "gns3-mcp not found": Ensure package is installed (pip list | findstr gns3-mcp)

  • "Connection refused": Verify GNS3 server is running and accessible

  • "Authentication failed": Check credentials in .env file

  • "Socket is closed": SSH session expired, reconnect automatically on next command

  • Dropped console connection: reopened by the next console operation (its result has warnings); after a GNS3 restart, if tools fail, gns3_connection(action="reconnect")

  • Node change "not applied by GNS3": the key is wrong for that node type or misplaced - check query_resource("nodes://<project_id>/<node_id>")

For Claude Desktop issues: Check logs at:

C:\Users\<username>\AppData\Roaming\Claude\logs\mcp-server-GNS3 Lab Controller.log

Advanced Setup

HTTP Mode Configuration

HTTP mode requires a persistent service and API key authentication. Only use if you need the service always running or network access from other machines.

Prerequisites:

  • .env file with GNS3 credentials

  • API key for authentication

Setup:

  1. Add to .env:

    # Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))"
    MCP_API_KEY=your-random-token-here
  2. Configure Claude Code:

    claude mcp add --transport http gns3-mcp http://127.0.0.1:8100/mcp --scope user `
      --header "MCP_API_KEY: your-random-token-here"
  3. Start server (in separate terminal):

    gns3-mcp --transport http --http-port 8100

Note: MCP_API_KEY is required for HTTP/SSE transport - the server refuses to start without it. Every HTTP entry point checks it (gns3-mcp, Docker, server.cmd install, python -m gns3_mcp.server.main). GET /health needs no key.

Windows Service Deployment

Run MCP server as a Windows service with WinSW and uvx (for HTTP mode).

📖 See PORTABLE_SETUP.md for detailed instructions.

Quick Setup:

# 1. Install uv (if not already installed)
pip install uv

# 2. Set environment variables from .env (requires Administrator)
.\set-env-vars.ps1

# 3. Install and start service (requires Administrator)
.\server.cmd install

Service Management:

# Check status
.\server.cmd status

# Start/stop/restart
.\server.cmd start
.\server.cmd stop
.\server.cmd restart

# After code updates
.\server.cmd reinstall        # Reinstall service

# Service from the local checkout (.venv, picks up code changes on restart)
.\server.cmd dev-install
.\server.cmd dev-reinstall

# Remove service
.\server.cmd uninstall

# Development mode (direct run, no service)
.\server.cmd run

After restarting the service, reconnect the MCP client (Claude Code: /mcp > gns3-mcp > Reconnect).

Key Features:

  • ✅ Portable: Works from any folder location (no hardcoded paths)

  • ✅ No venv: Uses uvx for automatic isolation

  • ✅ Secure: Credentials in Windows environment variables

  • ✅ Simple: Automated setup with PowerShell script

  • User: GNS3MCPService (low privilege, optional)

  • Startup: Automatic

  • Logs: mcp-http-server.log and GNS3-MCP-HTTP.wrapper.log

Manual Installation from Source

Requirements:

  • Python ≥ 3.10

  • GNS3 Server v3.x running and accessible

Setup:

# Install dependencies
pip install -r requirements.txt

# Create .env file
@"
GNS3_HOST=192.168.1.20
GNS3_PORT=80
GNS3_USER=admin
GNS3_PASSWORD=your-password
"@ | Out-File -FilePath .env -Encoding ASCII

# Run directly (STDIO mode, reads .env from the current directory)
python gns3_mcp\cli.py

# Or add to Claude Code (project-scoped)
claude mcp add --transport stdio gns3-mcp --scope project -- python "C:\full\path\to\gns3_mcp\cli.py"

Keep the password in .env rather than --password: command-line arguments are visible to other processes.

Quality checks and tests:

just check                                  # lint, format, type check, tests, version + changelog
python -m pytest tests\unit -q              # unit tests only
just bump minor                             # bump version in all three version files

Build .mcpb package:

just build
# Creates: mcp-server\mcp-server.mcpb

Release: push a vX.Y.Z tag - GitHub Actions publish PyPI, the .mcpb GitHub release and the Docker Hub image.


Docker Deployment

Docker Image Version Docker Pulls

Run GNS3 MCP Server in Docker for isolated deployment, easier management, and multi-platform support.

Quick Start with Docker Compose

Prerequisites:

  • Docker Desktop installed

  • GNS3 server running and accessible

  • Network access to GNS3 server

Step 1: Download docker-compose.yml

curl -O https://raw.githubusercontent.com/ChistokhinSV/gns3-mcp/master/docker-compose.yml

Step 2: Create .env file

cat > .env <<EOF
GNS3_HOST=192.168.1.20
GNS3_PORT=80
GNS3_USER=admin
GNS3_PASSWORD=your-password
MCP_API_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")
HTTP_PORT=8000
LOG_LEVEL=INFO
EOF

Or copy from template:

curl -O https://raw.githubusercontent.com/ChistokhinSV/gns3-mcp/master/.env.example
mv .env.example .env
# Edit .env with your credentials

Step 3: Start services

# Start MCP server and SSH proxy
docker-compose up -d

# View logs
docker-compose logs -f

# Check health
curl http://localhost:8000/health
curl http://localhost:8022/health

Step 4: Configure Claude Desktop/Code

For Claude Code (HTTP mode, key from .env):

claude mcp add --transport http gns3-mcp http://localhost:8000/mcp --scope user `
  --header "MCP_API_KEY: your-random-token-here"

For Claude Desktop, use the .mcpb package (STDIO) instead - see Installation.

Using Docker Run (without compose)

docker run -d \
  --name gns3-mcp-server \
  -p 8000:8000 \
  -e GNS3_HOST=192.168.1.20 \
  -e GNS3_PORT=80 \
  -e GNS3_USER=admin \
  -e GNS3_PASSWORD=your-password \
  -e MCP_API_KEY=your-random-token-here \
  --restart unless-stopped \
  chistokhinsv/gns3-mcp:latest

Container Management

# View logs
docker-compose logs -f gns3-mcp
docker-compose logs -f ssh-proxy

# Restart services
docker-compose restart

# Stop services
docker-compose down

# Update to latest version
docker-compose pull
docker-compose up -d

Environment Variables

Variable

Required

Default

Description

GNS3_HOST

Yes

-

GNS3 server IP/hostname

GNS3_PORT

No

80

GNS3 API port

GNS3_USER

Yes

-

GNS3 username

GNS3_PASSWORD

Yes

-

GNS3 password

MCP_API_KEY

Yes

-

Key clients send in the MCP_API_KEY header; container exits without it

HTTP_PORT

No

8000

MCP server port

LOG_LEVEL

No

INFO

Logging level

GNS3_MCP_UPDATE_CHECK

No

true

false: gns3_connection check does not look up newer releases on PyPI

GNS3_USE_HTTPS

No

false

Use HTTPS for GNS3

GNS3_VERIFY_SSL

No

true

Verify SSL certs

GNS3_NODE_CREATE_TIMEOUT

No

180

Seconds node create waits for GNS3 (first use of a template with big images is slow)

GNS3_NODE_CREATE_RECOVERY_WAIT

No

60

Seconds to keep looking for the node after that timeout, then name and place it

See .env.example for complete list.

Architecture

The Docker deployment includes two containers:

  1. gns3-mcp - Main MCP server (port 8000, endpoint /mcp)

    • Provides MCP protocol access to GNS3

    • Streamable HTTP transport, MCP_API_KEY header auth; GET /health open for the healthcheck

    • Bridge network mode

  2. gns3-ssh-proxy - SSH gateway (port 8022)

    • Enables SSH access to lab devices

    • Host network mode (required for isolated lab networks)

    • Netmiko-based automation

Troubleshooting

Container won't start:

docker-compose logs gns3-mcp
docker-compose logs ssh-proxy

Cannot connect to GNS3:

# Test from container
docker exec gns3-mcp-server curl -v http://192.168.1.20/v3/version

# Check connectivity
docker exec gns3-mcp-server ping -c 3 192.168.1.20

Health check failing:

# Manual health check
curl -v http://localhost:8000/health

# Check container status
docker ps --filter name=gns3-mcp

For more details, see docs/DOCKER_HUB.md.


Documentation

License

MIT License

GNS3 MCP Server and the GNS3 Lab plugin are a community project, not made or endorsed by the GNS3 project or GNS3 Technologies. GNS3 is a trademark of its owners.

Author

Sergei Chistokhin (Sergei@Chistokhin.com)

Available Tools

15 tools
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
... ])

Inputs: operations (required). Returns: result

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

Inputs: action (required), x, y, z, +22 more. Returns: result

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.

Inputs: output_path (required), crop_x, crop_y, format, +2 more. Returns: result

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

Inputs: action (required). Returns: result

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

Inputs: url (required), action (required), headers, timeout, +1 more. Returns: result

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

Inputs: action (required), x, y, z, +21 more. Returns: result

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

Inputs: action (required), node_name (required), content, file_path, +1 more. Returns: result

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

Inputs: action (required), mode, limit, project_id, +1 more. Returns: result

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)

Inputs: action (required), name, path, format, +1 more. Returns: result

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

Inputs: action (required), content, project_id. Returns: result

query_resourceC

Universal resource query tool - access any GNS3 MCP resource.

See tool implementation docstring for comprehensive URI pattern documentation.

Inputs: uri (required), format. Returns: result

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

Inputs: category, capability, resource_uri. Returns: result

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

Inputs: operations (required). Returns: result

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
}

Inputs: action (required), content, filename. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    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

    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
      C
      quality
      C
      maintenance
      Enables AI agents to control GNS3 network emulation labs. Supports building topologies, managing devices, capturing packets, and automating device CLIs.
      100
      2
      MIT