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

# 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

# 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

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

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

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

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

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

# 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

# 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

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

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

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 (Sergei@Chistokhin.com)