Netbrain MCP

🚀 NetBrain MCP

NetBrain MCP is an open - source network operation integration platform that connects large language models (LLMs) with network devices through the Model Context Protocol (MCP). It enables AI assistants to perform network configuration, diagnosis, and management tasks via a standardized protocol.

🎉 Project Status: All planned functions are completed and ready for production - environment deployment

🚀 Quick Start

🔧 MCP Server Mode

Run directly using Python

python server.py

Run using MCP development tools

mcp run server.py

Run with a debugging interface (MCP Inspector)

mcp dev server.py

🚀 Production - Environment Deployment

# Install dependencies
pip install -r requirements.txt

# Start the server
python server.py

✨ Features

🔧 Core Features

• Network Device Management - Unified management of network devices from various vendors (Cisco, Huawei, etc.).
• Device Connection - Support for connecting to network devices via SSH and Telnet protocols.
• Command Execution - Remotely execute network commands and obtain results.
• Credential Management - Securely manage device access credentials.
• MCP Protocol Support - Enable large language models to access and control network devices.
• Resource Provisioning Function - Provide resources such as devices and configurations to LLMs via URIs.
• Prompt Template System - Provide dedicated prompt templates for network diagnosis, configuration review, etc.

🌐 Web Interface Features

• Professional Terminal Experience - A multi - tab terminal based on XTerm.js, supporting command completion and history.
• Network Topology Visualization - An interactive topology map based on D3.js, supporting automatic discovery via CDP/LLDP.
• Device Management Interface - An intuitive interface for adding, editing, and monitoring device status.
• Session Management - Manage multiple device connection sessions, supporting reconnection and heartbeat detection.
• Theme System - A complete dark/light theme switch, including the login page.
• Responsive Design - A modern user interface compatible across devices.

🚀 Advanced Features

• Automatic Topology Discovery - Automatically identify the network topology based on the CDP/LLDP protocol.
• Intelligent Device Identification - Built - in vendor MAC address identification function to automatically infer device types.
• Data Persistence - A JSON file storage system supporting data backup and recovery.
• Multi - Vendor Support - Compatible with devices from mainstream vendors such as Cisco, Huawei, and H3C.
• Command Template Library - Preset vendor - specific command templates and configuration snippets.
• Network Scanning - Support for network range scanning and automatic device discovery.

🔧 Technical Details

🔧 Back - end Technology Stack

• Language: Python 3.10+
• MCP Framework: FastMCP (based on the mcp Python package)
• Web Framework: FastAPI + WebSocket
• Device Connection: Scrapli (supporting asynchronous/synchronous hybrid mode)
• Asynchronous Support: Use asyncio for efficient network operations.
• Data Storage: JSON file storage + in - memory cache
• Modular Design: Independent modules for network device management, connectors, tool management, and resource provisioning.

🌐 Front - end Technology Stack

• Terminal Emulation: XTerm.js - A professional - grade terminal experience.
• Data Visualization: D3.js - Network topology visualization.
• Real - time Communication: WebSocket - Two - way real - time communication.
• Interface Framework: Modern web technologies + CSS3 animations.
• Theme System: CSS variables + JavaScript theme management.
• Responsive Design: Flexbox + Grid layout.

📚 Documentation

System Components

🔧 Core Components

• Tool Manager (tool_manager.py): Manage tool registration, classification, and invocation.
• Device Manager (network_devices.py): Manage network device information and credentials.
• Connection Manager (device_connector.py): Handle connections to network devices and command execution.
• Resource Manager (mcp_resources.py): Manage MCP resources and prompt templates.
• MCP Server (server.py): Provide MCP interfaces and integrate other components.
• Template System (template_system.py): Provide AI prompt template management and rendering.

🌐 Web Interface Components

• Web Server (web/app.py): A FastAPI web server providing RESTful APIs and WebSocket support.
• WebSocket Terminal (web/static/js/terminal.js): Real - time terminal communication and XTerm.js integration.
• Topology Visualization (web/static/js/topology.js): A D3.js network topology rendering engine.
• Theme Management (web/static/js/theme.js): Global theme switching and persistence.
• Device Management Interface (web/templates/): HTML templates and user interfaces.

🚀 Extension Components

• Topology Discovery Engine (topology_discovery_improved.py): Network topology discovery based on the CDP/LLDP protocol.
• Network Scanner (network_scanner.py): Network range scanning and vendor MAC address identification.
• Device Prompt Templates (device_prompts.py): Device - specific AI prompt templates.
• Data Storage Layer (data/): JSON file storage and data persistence.
• Command Template Library (templates/): Vendor - specific command templates and configuration snippets.

Available Tools

NetBrain MCP provides the following network management tools:

Device Management Tools

• list_devices - List network devices, supporting filtering by vendor, type, status, and tags.
• add_device - Add a new network device.
• get_device - Get detailed device information.
• update_device - Update device information.
• delete_device - Delete a device.

Credential Management Tools

• add_credential - Add device access credentials.
• list_credentials - List all device credentials.

Device Connection Tools

• connect_device - Connect to a network device.
• disconnect_device - Disconnect from a network device.
• send_command - Send a command to a network device.
• send_commands - Send multiple commands to a network device.
• get_active_connections - Get currently active device connections.

Topology Discovery Tools

• discover_topology - Automatically discover the network topology based on the CDP/LLDP protocol.
• get_topology - Get discovered topology data.
• clear_topology - Clear topology data.
• get_device_neighbors - Get device neighbor information.
• discover_device_neighbors - Discover neighbors of a single device.
• get_topology_statistics - Get topology statistics.

Network Scanning Tools

• scan_network_range - Scan a network address range.
• get_scan_results - Get network scan results.
• get_scan_statistics - Get scan statistics.
• discover_devices_from_scan_results - Discover devices from scan results.
• clear_scan_results - Clear scan results.
• scan_single_host - Scan a single host.

Resource Management Tools

• list_resources - List available MCP resources.
• get_resource - Get a resource with a specified URI.
• clear_resource_cache - Clear the resource cache.

Template Management Tools

• list_templates - List available prompt templates.
• render_template - Render a prompt template.

Testing Tools

• test_scrapli_connection - Test a Scrapli connection.
• test_telnet_connection - Test a Telnet connection.
• send_telnet_command - Send a Telnet command.

Available Resources

NetBrain MCP provides the following MCP resources:

Device Resources

• device/{device_id} - Get detailed device information.
• device/{device_id}/config - Get device configuration information.
• device/{device_id}/interfaces - Get device interface information.
• device/{device_id}/routes - Get device routing table information.
• device/{device_id}/neighbors - Get device neighbor information.

Topology Resources

• topology - Get network topology data.
• topology/statistics - Get topology statistics.

Scanning Resources

• scan/results - Get network scan results.
• scan/statistics - Get scan statistics.
• scan/result/{ip_address} - Get scan results for a specific IP.

System Resources

• greeting/{name} - Get a personalized greeting.
• system/status - Get system status information.
• credentials - Get all credential information (sensitive information is脱敏).

Prompt Templates

NetBrain MCP provides the following prompt templates:

• device_diagnosis - Device diagnosis prompt template.
• config_review - Device configuration review prompt template.
• route_analysis - Route analysis prompt template.
• network_diagnosis - Network diagnosis prompt template.
• vlan_config - VLAN configuration generation template.
• network_topology - Network topology analysis template.
• network_security - Network security assessment template.

💻 Usage Examples

🌐 Web Interface Usage

1. Start the server

   python server.py
   

2. Access the Web interface
   • Open a browser and visit http://localhost:8088.
   • Log in to the system using the login page.
3. Use the terminal function
   • Click the "Terminal" tab.
   • Add a new device or select an existing one.
   • Establish an SSH/Telnet connection.
   • Enjoy a professional - grade terminal experience (command completion, history, etc.).
4. View the network topology
   • Click the "Network Topology" tab.
   • Click "Discover Topology" to start an automatic scan.
   • View the visualized network topology map.
   • Double - click a node to quickly connect to a device.
5. Manage devices
   • Add and edit device information on the "Devices" page.
   • Configure device credentials and connection parameters.
   • Monitor device online status.

🔧 MCP Protocol Usage

You can test the functions through the following steps:

1. Run the MCP server.
2. Use the MCP Inspector to view available tools.
3. Use the list_devices tool to list pre - configured devices.
4. Connect to a device using the device ID and credential ID.
5. Send commands to view simulated output.

📊 Resource Access Examples

Get device information:

GET device/1

Get device configuration:

GET device/1/config

Get topology data:

GET topology

Use a prompt template:

POST render_template
{
  "template_name": "device_diagnosis",
  "context": {
    "device_info": "...",
    "interfaces_info": "..."
  }
}

🚀 Advanced Function Examples

Automatic Topology Discovery:

# Invoke through an MCP tool
discover_topology({
  "device_ids": "device1,device2"
})

Network Scanning:

# Scan a network range
scan_network_range({
  "network": "192.168.1.0/24",
  "timeout": 3.0,
  "auto_create_devices": true
})

Batch Device Configuration:

# Use a command template
send_commands({
  "device_id": "cisco_router_1", 
  "credential_id": "admin_cred",
  "commands": "interface gi0/1;ip address 192.168.10.1 255.255.255.0;no shutdown"
})

📚 Project Highlights

🎯 Completed Core Functions

✅ Complete MCP Protocol Implementation - A standardized AI - device communication protocol based on FastMCP. ✅ Professional - Grade Terminal Experience - Based on XTerm.js, supporting command completion, history, and real prompts. ✅ Network Topology Visualization - An interactive topology map based on D3.js, supporting automatic discovery via CDP/LLDP. ✅ Multi - Vendor Device Support - Unified access to devices from mainstream vendors such as Cisco, Huawei, and H3C. ✅ Modern Web Interface - Responsive design, dark/light themes, and cross - device compatibility. ✅ Data Persistent Storage - JSON file storage with automatic backup and recovery. ✅ Intelligent Device Identification - Built - in vendor MAC address library for automatic device type inference. ✅ Network Scanning Function - Support for large - scale network discovery and automatic device identification.

🚀 Technical Features

• Highly Modular Architecture - An extensible design based on the abstract factory and strategy patterns.
• Asynchronous Performance Optimization - A fully asynchronous architecture for high - concurrency processing capabilities.
• AI - Driven Operations - The MCP protocol enables seamless integration of AI with network devices.
• Professional Engineering Practices - Complete error handling, logging, and configuration management.
• Hybrid Connection Mode - Scrapli's intelligent adaptation between asynchronous and synchronous modes ensures optimal compatibility.

🔮 Future Expansion Directions

Although the core functions of the project are completed, the following enhancements can be considered in the future:

• Enterprise - Level Functions - User permission management, audit logs, and compliance reports.
• Monitoring and Alerts - Network performance monitoring, automatic fault diagnosis, and predictive maintenance.
• Protocol Expansion - Support for more network protocols such as SNMP, NETCONF, and RESTCONF.
• Virtualization Integration - Support for network simulators such as eNSP, GNS3, and EVE - NG.
• Enhanced AI Capabilities - Intelligent analysis of network faults and configuration optimization suggestions.

📄 Project Team

• Technical Lead: Koreyoshi - MCP protocol implementation and system architecture design.
• Function Development: Koreyoshi - Device management, data storage, and topology discovery.
• Front - End Development: Koreyoshi - Web interface, terminal functions, and visualization design.

🤝 Contribution

Welcome to submit your suggestions and improvements via Pull Requests or Issues.