gns3-mcp 0.54.2

GNS3 lab automation MCP server with AI agent integration

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.

Version: 0.49.0

Features

• 15 Tools: CRUD-style GNS3 automation (v0.47.0: 53% consolidation from 32 tools)
• 25 Resources: Read-only data access (projects, nodes, links, sessions, topology reports)
• CRUD Pattern: Consolidated tools with action parameters (project(action="open"), node(action="create"), etc.)
• Batch Operations: Console and SSH operations use batch-only APIs for atomic execution
• Wildcard Support: Node operations support patterns (*, Router*, R[123], JSON arrays)
• Project Management: Create, open, close GNS3 projects
• Node Control: Start/stop/restart nodes with wildcard patterns and parallel execution
• Console Access: Telnet console automation with pattern matching and grep filtering
• SSH Automation: Network device automation via Netmiko (200+ device types)
• Network Topology: Batch connect/disconnect links, create drawings, export diagrams
• Docker Integration: Configure container networks, read/write files
• Tool Discovery: search_tools() with category/capability/resource filtering
• Claude Desktop Support: All resources accessible via tools (query_resource, list_projects, list_nodes, get_topology)
• Security: API key authentication (HTTP mode), service privilege isolation, HTTPS support

Installation

Supported Platform: Windows only

Quick Start (Claude Code - Recommended)

Prerequisites:

• Windows 10/11
• 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 (Detailed Setup)

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

Claude Desktop (.mcpb Package)

Claude Desktop Setup

Installation:

1. Download the latest .mcpb package:

   • From Releases
   • Or build locally: just build (creates mcp-server\mcp-server.mcpb)

2. Install by double-clicking the .mcpb file

3. Configure credentials in Claude Desktop:

   • Open Claude Desktop
   • Go to Settings > Developer > Edit Config
   • Find gns3-mcp server
   • Add environment variables:

     {
       "GNS3_HOST": "192.168.1.20",
       "GNS3_PORT": "80",
       "GNS3_USER": "admin",
       "GNS3_PASSWORD": "your-password"
     }
     

4. Restart Claude Desktop

5. Check logs if issues occur:

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

Cursor & Windsurf (JSON Configuration)

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

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

3. Restart Windsurf

Note: Cursor and Windsurf use identical configuration formats.

---

Troubleshooting

Connection Issues:

# Test GNS3 server connectivity
curl http://192.168.1.20:80/v3/projects

# 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

For Claude Desktop issues: Check logs at:

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

---

Advanced Setup

HTTP Mode (Always-Running Service)

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: If MCP_API_KEY is missing from .env, it will be auto-generated on first start and automatically saved to .env for persistence.

Windows Service (Production Deployment)

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

# Remove service
.\server.cmd uninstall

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

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

Development Setup (Contributors)

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 - no authentication)
python gns3_mcp\cli.py --host 192.168.1.20 --port 80 --username admin --password your-password

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

Build .mcpb package:

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

---

Docker Deployment

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

claude mcp add --transport http gns3-mcp --url http://localhost:8000

For Claude Desktop, add to MCP configuration:

{
  "mcpServers": {
    "gns3-mcp": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8000"
      }
    }
  }
}

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 \
  --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
HTTP_PORT	No	8000	MCP server port
LOG_LEVEL	No	INFO	Logging level
GNS3_USE_HTTPS	No	false	Use HTTPS for GNS3
GNS3_VERIFY_SSL	No	true	Verify SSL certs

See .env.example for complete list.

Architecture

The Docker deployment includes two containers:

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

   • Provides MCP protocol access to GNS3
   • HTTP/SSE transport modes
   • 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

• CHANGELOG.md - Version history and release notes
• DEPLOYMENT.md - SSH proxy deployment instructions
• docs/architecture/ - Architecture documentation and C4 diagrams

License

MIT License

Author

Sergei Chistokhin ([e-mail])