NetContext

AI-powered network automation through Model Context Protocol for SSH-based network device management.

CI License: GPL v3

---

What is NetContext MCP?

NetContext provides an MCP server that enables AI assistants (Claude Desktop, LM Studio, etc.) to execute commands on network devices via SSH. Control your network infrastructure using natural language through your favorite AI tools.

Features

• ✅ Production-Ready SSH Support: Tested with real devices (Aruba switches, UniFi routers)
• 🔐 Multiple Authentication Methods: Password, keyboard-interactive, SSH keys, SSH agent
• 🏗️ Protocol Abstraction: Clean architecture supporting legacy and modern SSH implementations
• 📟 Device Pagination Handling: Automatic detection and handling of CLI pagination prompts
• 🛡️ Security First: Command sanitization, credential protection, timeout management
• ⚡ Batch Operations: Execute commands on multiple devices in parallel
• 🐳 Docker Test Environment: Pre-configured SSH test servers for development

---

Supported Devices

Vendor	Model	Authentication	Status
Cisco	IOS/IOS-XE (Catalyst/ISR/ASR)	Password/Keys/Keyboard-int	✅ Production
HP/Aruba	ProCurve Switches (2530/2920)	Password	✅ Production
Ubiquiti	UniFi Dream Router	Keyboard-interactive	✅ Production
Generic	Linux/SSH servers	Password/Keys	✅ Supported

Key Capabilities:

• Multi-Vendor Support: Cisco, HP/Aruba, Ubiquiti, and generic SSH devices
• Legacy SSH Support: Works with older network equipment (diffie-hellman-group14-sha1, ssh-rsa)
• Modern SSH Support: Full support for current algorithms (curve25519-sha256, chacha20-poly1305)
• Device-Specific Handling: Pagination, prompt detection, vendor-specific commands
• Error Detection: Cisco-specific error pattern recognition and reporting

---

Quick Start

1. Installation

# Clone repository
git clone https://github.com/hgursel/NetContext-MCP.git
cd NetContext-MCP

# Install dependencies
npm install

# Build the MCP server
npm run build

2. Setup with Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent:

{
  "mcpServers": {
    "netcontext-network": {
      "command": "node",
      "args": [
        "/path/to/NetContext-MCP/packages/network-mcp/dist/index.js"
      ],
      "env": {
        "DEVICE_USERNAME": "admin",
        "DEVICE_PASSWORD": "your-default-password",
        "SSH_TIMEOUT": "10000",
        "DEFAULT_PROTOCOL": "ssh"
      }
    }
  }
}

Important:

• Replace /path/to/NetContext-MCP with your actual installation path
• Default credentials can be overridden per-command
• For production, use SSH keys instead of passwords (see Security)

3. Setup with LM Studio

LM Studio supports MCP servers through configuration. Add to your LM Studio MCP config:

{
  "mcpServers": {
    "netcontext": {
      "command": "node",
      "args": ["/path/to/NetContext-MCP/packages/network-mcp/dist/index.js"],
      "env": {
        "DEVICE_USERNAME": "admin",
        "SSH_TIMEOUT": "10000"
      }
    }
  }
}

4. Restart Your AI Client

• Claude Desktop: Quit (Cmd+Q) and restart
• LM Studio: Restart the application
• Other MCP Clients: Follow their restart procedure

5. Test the Connection

In your AI assistant, try:

Execute "show version" on my Aruba switch at 192.168.1.10 with username manager and password mypassword

or

Run "uname -a" on UniFi router at 10.10.21.1 with username root and password mypassword

---

Usage Examples

Aruba ProCurve Switch

Show version information on the Aruba switch at 192.168.2.217 with credentials manager/password

What happens:

1. MCP server connects via SSH (handles legacy algorithms automatically)
2. Detects CLI prompt and disables pagination
3. Executes show version command
4. Returns device model, software version, serial number

Example output:

HP J9729A 2920-48G-POE+ Switch
Software revision WB.16.02.0012
Serial Number: CNXXXXXXXX

Cisco IOS/IOS-XE Router or Switch

Get device information from Cisco router at 192.168.1.1 with credentials admin/cisco123

What happens:

1. MCP server connects via SSH (supports password, keyboard-interactive, or SSH keys)
2. Automatically sends terminal length 0 to disable pagination
3. Executes show version command
4. Detects Cisco error patterns if command fails

Example output:

Cisco IOS Software, C2960X Software (C2960X-UNIVERSALK9-M), Version 15.2(7)E8
Technical Support: http://www.cisco.com/techsupport
System image file is "flash:c2960x-universalk9-mz.152-7.E8.bin"
uptime is 45 weeks, 2 days, 3 hours, 15 minutes

Available Command Bundles (in vendor/cisco-ios-iosxe/commands.yml):

• health_check - Basic system health (version, interfaces, CPU, memory)
• security_audit - Security configuration review
• interface_troubleshooting - Interface diagnostics
• vlan_troubleshooting - VLAN configuration and connectivity (switches)
• routing_troubleshooting - Routing table and protocols (routers)

UniFi Dream Router

Get system information from UniFi router at 10.10.21.1 with username root and password mypassword

What happens:

1. MCP server connects via SSH (uses keyboard-interactive auth)
2. Executes Linux command: uname -a
3. Returns kernel and firmware version

Example output:

Linux UDR7 5.4.213-ui-ipq5322-wireless #5.4.213 SMP PREEMPT aarch64 GNU/Linux
Firmware version: v4.3.9

Batch Execution

Get uptime from these devices in parallel:
- Aruba switch at 192.168.2.217 (manager/password)
- UniFi router at 10.10.21.1 (root/mypassword)

What happens:

1. MCP server executes commands on both devices simultaneously
2. Returns combined results with per-device status
3. Shows execution time for each device

---

Configuration

Environment Variables

Configure in your MCP client's config file:

Variable	Description	Default
DEVICE_USERNAME	Default SSH username	netadmin
DEVICE_PASSWORD	Default SSH password	testpass123
SSH_TIMEOUT	Connection timeout (ms)	10000
DEFAULT_PROTOCOL	Protocol to use	ssh
SSH_VERIFY_HOST_KEY	Verify SSH host keys	false

Per-Command Credentials

You can override default credentials in each command:

Execute "show vlan" on 192.168.1.10 with username admin and password secret123

SSH Key Authentication

For production use, configure SSH keys:

{
  "env": {
    "DEVICE_USERNAME": "admin",
    "DEVICE_PRIVATE_KEY": "/home/user/.ssh/network_devices_rsa"
  }
}

---

Architecture

Protocol Abstraction Layer

┌─────────────────────────────────────────┐
│     AI Assistant (Claude/LM Studio)     │
└────────────────┬────────────────────────┘
                 │ MCP Protocol
                 │
┌────────────────▼────────────────────────┐
│       NetContext MCP Server             │
│                                         │
│  Tools:                                 │
│  - execute_commands                     │
│  - batch_execute                        │
│  - execute_bundle                       │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│      Protocol Abstraction Layer         │
│                                         │
│  - SSHProtocol                          │
│  - Credential Management                │
│  - Command Sanitization                 │
│  - Error Handling                       │
└────────────────┬────────────────────────┘
                 │ SSH (various auth methods)
                 │
┌────────────────▼────────────────────────┐
│         Network Devices                 │
│                                         │
│  - Aruba Switches (legacy SSH)          │
│  - UniFi Routers (keyboard-interactive) │
│  - Linux Servers (standard SSH)         │
└─────────────────────────────────────────┘

Supported Authentication Methods

1. Password Authentication: Standard username/password
2. Keyboard-Interactive: Challenge-response (UniFi, some Linux systems)
3. SSH Private Key: Key-based authentication
4. SSH Agent: Agent forwarding support

Device-Specific Features

• Aruba Switches: Pagination handling ("Press any key to continue"), legacy SSH algorithms, HP ProCurve CLI
• UniFi Routers: Keyboard-interactive auth, modern SSH algorithms, standard Linux commands
• Generic Devices: Standard SSH with comprehensive algorithm support

---

Security Best Practices

Credential Management

❌ Don't hardcode passwords in configuration files:

{
  "env": {
    "DEVICE_PASSWORD": "admin123"  // Bad!
  }
}

✅ Do use SSH keys:

{
  "env": {
    "DEVICE_USERNAME": "admin",
    "DEVICE_PRIVATE_KEY": "/home/user/.ssh/network_key"
  }
}

✅ Do use environment variables:

# In .bashrc or .zshrc
export DEVICE_USERNAME=admin
export DEVICE_PRIVATE_KEY=/home/user/.ssh/network_key

Command Sanitization

The MCP server automatically blocks dangerous commands:

• ✅ Blocks: rm, del, format, erase, write erase
• ✅ Blocks: Command chaining (&&, ||, ;)
• ✅ Blocks: Path traversal (../)
• ✅ Blocks: Output redirection (<, >)

Network Security

• Limit SSH access: Use ACLs to restrict management access
• Use jump hosts: Don't expose devices directly to internet
• Enable logging: Monitor all SSH sessions
• Rotate credentials: Regular password/key rotation
• Read-only accounts: Use when possible

---

Development

Prerequisites

• Node.js 18.x or later
• npm 9.x or later
• TypeScript 5.x

Build from Source

# Clone repository
git clone https://github.com/hgursel/NetContext-MCP.git
cd NetContext-MCP

# Install dependencies
npm install

# Build all packages
npm run build

# Run tests
npm test

Docker Test Environment

For development and testing without real devices:

# Start test SSH servers
cd docker
docker-compose up -d

# Test connection
ssh -i test-ssh-server/keys/test_key -p 2223 netadmin@localhost 'show version'

# Stop servers
docker-compose down

The Docker environment provides:

• 2 SSH test servers (password auth + key auth)
• Mock network device commands
• Safe testing environment

---

Troubleshooting

MCP server not loading

Symptoms: Tools not available in AI assistant

Solutions:

1. Check config file syntax (must be valid JSON)
2. Verify path to index.js is absolute and correct
3. Restart AI client completely
4. Check logs: ~/Library/Logs/Claude/mcp-server-netcontext-network.log

SSH connection fails

Symptoms: Connection timeout or Authentication failed

Solutions:

• Verify device is reachable: ping <IP>
• Test SSH manually: ssh user@<IP>
• Check credentials are correct
• Verify SSH is enabled on device
• For Aruba: Legacy SSH algorithms supported automatically
• For UniFi: Keyboard-interactive auth supported automatically

Commands return no output

Symptoms: Empty output or timeout

Solutions:

• Increase SSH_TIMEOUT in config (e.g., 15000)
• Check device CLI prompt format (should detect # or >)
• Verify command syntax for specific device
• Check pagination handling (automatic for most devices)

Keyboard-interactive auth fails (UniFi)

Solution: Ensure tryKeyboard: true is enabled (automatic in code)

---

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-vendor
3. Add tests for new functionality
4. Submit a pull request

Areas for contribution:

• Additional device vendor support
• Protocol implementations (HTTP API, NETCONF)
• Enhanced error handling
• Documentation improvements

---

Roadmap

Current (v0.1.0)

• ✅ SSH protocol with multiple auth methods
• ✅ Aruba ProCurve switch support
• ✅ UniFi Dream Router support
• ✅ Docker test environment
• ✅ Command sanitization and security

Planned (v0.2.0)

• HTTP API protocol (for REST-based devices)
• Configuration file for credential management
• Protocol detection system
• Vendor metadata database
• Command bundles (health checks, audits)

Future (v1.0.0)

• Cisco IOS/IOS-XE support
• Juniper JunOS support
• NETCONF protocol support
• Configuration backup/restore
• Change management workflows

---

License

GNU General Public License v3.0 - see LICENSE file for details.

---

Acknowledgments

• Anthropic: For the Model Context Protocol specification
• HP/Aruba: For ArubaOS-Switch documentation
• Ubiquiti: For UniFi OS
• Community: For testing and feedback

---

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Related Projects

• Model Context Protocol: https://modelcontextprotocol.io
• Claude Desktop: https://claude.ai/download
• LM Studio: https://lmstudio.ai

---

NetContext MCP - Network automation through natural language

Independent project, not affiliated with Anthropic, HP, Aruba, Ubiquiti, or any vendor.