ContainerLab MCP Server

This MCP (Model Context Protocol) server provides tools for interacting with ContainerLab Linux containers acting as network clients. It enables network configuration, connectivity testing, and routing management for network clients in the lab environments. This MCP server is limited to discovering and automating tasks on clab nodes of type Linux.

Docker Build

Standard Build

docker build . -t clab-mcp-server

Build with Proxy (if behind corporate proxy)

docker build . --build-arg HTTP_PROXY=<proxy server> --build-arg HTTPS_PROXY=<proxy server> --build-arg NO_PROXY=<subnets to skip> -t clab-mcp-server

Configuration

Docker Host Configuration

The MCP server needs to connect to a Docker daemon to manage ContainerLab containers. You can configure the Docker host IP address in several ways:

1. Environment Variable (recommended for Docker runs):

   export DOCKER_HOST_IP=your.docker.host.ip
   

2. Command Line Argument (for direct Python execution):

   python clab_mcp_server.py --docker-host-ip your.docker.host.ip
   

3. Default Behavior: If neither is specified, it defaults to localhost

Available Command Line Options

python clab_mcp_server.py --help

• --docker-host-ip: Docker host IP address (default: localhost, or set DOCKER_HOST_IP env var)
• --docker-port: Docker daemon port (default: 2375)
• --docker-tls: Use TLS for Docker connection (default: False)
• --mcp-host: MCP server host (default: 0.0.0.0)
• --mcp-port: MCP server port (default: 8989)

Docker Run

Important: This MCP server connects to the CLAB server using Docker TCP transport. The CLAB Docker service must be enabled to be managed by Docker TCP-based commands.

Basic Run (Docker host on localhost)

docker run -d -p 8989:8989 clab-mcp-server

Run with Custom Docker Host IP

docker run -d --name clab-mcp-server -p 8989:8989 -e DOCKER_HOST_IP=<docker-host-ip> clab-mcp-server

Run with Multiple Environment Variables

docker run -d -p 8989:8989 \
  -e DOCKER_HOST_IP=<docker-host-ip> \
  -e DOCKER_PORT=2375 \
  --name clab-mcp-server \
  clab-mcp-server

Port 8989 is used because the MCP server inside the container listens on port 8989. The port mapping -p 8989:8989 makes the server accessible from the host.

Available Tools

Network Discovery

• get_clab_linux_nodes - Discover and inventory all ContainerLab Linux nodes with their network interface details

Interface Configuration

• set_ip - Configure network connectivity by creating VLAN interfaces and assigning IP addresses
• delete_vlan_interface - Remove VLAN interfaces and clean up network configuration

Bond Interface Management

• create_bond_interface - Create bond interfaces for network redundancy and load balancing
• delete_bond_interface - Delete bond interfaces and restore slave interfaces to their original state

Interface Inspection & Troubleshooting

• get_interface_info - Retrieve comprehensive configuration and status information for network interfaces (supports physical, VLAN, and bond interfaces)
• test_connectivity - Verify network connectivity between containers using ping
• lldp_neighbor_discovery - Discover LLDP neighbors and network topology around containers

Routing Configuration

• add_static_route - Add static routes to container routing tables for L3 domain testing
• check_routes - Retrieve and analyze container routing tables for troubleshooting
• route_delete - Remove static routes from container routing tables

Tool Details

Network Discovery Tools

get_clab_linux_nodes

Discovers all running ContainerLab containers with the clab-node-kind label set to "linux" and retrieves detailed network interface information including IP addresses, MAC addresses, and interface states.

Use Cases:

• Network topology discovery
• Interface configuration verification
• MAC address learning
• Connectivity troubleshooting

Interface Configuration Tools

set_ip

Creates VLAN interfaces and assigns IP addresses with optional gateway configuration.

Parameters:

• container_name: Target container name
• interface_name: Base interface name (e.g., 'eth1')
• ip_with_mask: IP address with CIDR notation (e.g., '192.168.1.10/24')
• vlan_id: VLAN ID number (1-4094)
• gateway_ip: Optional default gateway IP address

Operations:

1. Creates VLAN interface (e.g., eth1.100 for VLAN 100)
2. Brings the interface up
3. Assigns IP address
4. Optionally configures default gateway

delete_vlan_interface

Removes VLAN interfaces and cleans up associated configuration.

Parameters:

• container_name: Target container name
• interface_name: Base interface name
• vlan_id: VLAN ID to delete

Bond Interface Management Tools

create_bond_interface

Creates bonded network interfaces for redundancy and load balancing.

Parameters:

• container_name: Target container name
• bond_name: Bond interface name (e.g., 'bond0')
• slave_interfaces: List of interfaces to bond (e.g., ['eth1', 'eth2'])
• bond_mode: Bonding mode (default: 'active-backup')
• miimon: MII monitoring interval in milliseconds (default: 100)

Supported Bond Modes:

• active-backup: One interface active, others standby
• balance-rr: Round-robin load balancing
• balance-xor: XOR hash load balancing
• broadcast: Transmit on all interfaces
• 802.3ad: IEEE 802.3ad dynamic link aggregation (LACP)
• balance-tlb: Adaptive transmit load balancing
• balance-alb: Adaptive load balancing

delete_bond_interface

Removes bond interfaces and restores slave interfaces to independent operation.

Parameters:

• container_name: Target container name
• bond_name: Bond interface name to delete
• slave_interfaces: List of slave interfaces to restore

Operations:

1. Brings down bond interface
2. Removes slave interfaces from bond
3. Deletes bond interface
4. Restores slave interfaces as independent interfaces

Interface Inspection & Troubleshooting Tools

get_interface_info

Provides comprehensive inspection of network interfaces with specialized support for different interface types.

Parameters:

• container_name: Target container name
• interface_name: Interface to analyze (e.g., 'eth1', 'bond0', 'eth1.100')

Returns detailed information about:

• Basic Properties: State (up/down), MAC address, MTU
• IP Configuration: All assigned IP addresses with CIDR notation
• Bond Details (for bond interfaces):
  • Bond mode and configuration parameters
  • Slave interface status and active/backup states
  • MII monitoring status and link state
  • Currently active slave identification
• VLAN Details (for VLAN interfaces):
  • VLAN ID and parent interface
  • VLAN-specific configuration
• Statistics: RX/TX packets, bytes, errors, dropped packets

Use Cases:

• Post-configuration verification after set_ip or create_bond_interface
• Network troubleshooting and diagnostics
• Bond interface health monitoring
• Interface performance analysis

test_connectivity

Tests network reachability between containers using ICMP ping.

Parameters:

• container_name: Source container name
• destination_ip: Target IP address to test

Features:

• Sends 3 ping packets with 2-second timeout
• Provides detailed connectivity diagnostics
• Includes troubleshooting guidance for common failure scenarios

lldp_neighbor_discovery

Discovers Link Layer Discovery Protocol (LLDP) neighbors connected to a container's network interfaces, providing visibility into network topology and directly connected devices.

Parameters:

• container_name: Target container name

Automatic Setup (Idempotent):

1. Attempts to run lldpcli show neighbors
2. If lldpcli not found, automatically installs lldpd package
3. If daemon not running, automatically starts lldpd daemon
4. Retries neighbor discovery after setup is complete

LLDP Information Provided:

• Neighbor device chassis ID and system name
• Connected port identifiers and descriptions
• Device capabilities (router, switch, bridge, etc.)
• Management IP addresses
• VLAN information
• System description and version details

Returns:

• status: 'success' or 'error'
• neighbors_output: Raw LLDP output showing neighbor information
• neighbors_found: Boolean indicating if neighbors were discovered
• messages: List of operations performed (installation, daemon start, etc.)
• lldpd_installed: Boolean indicating if lldpd was installed during this run
• daemon_started: Boolean indicating if lldpd daemon was started during this run
• error: Error message if operation failed

Use Cases:

• Network topology discovery and mapping
• Cable tracing and port identification
• Verifying physical/logical connectivity to network devices
• Identifying which switch ports containers are connected to
• Network troubleshooting and validation
• Lab environment verification
• Network device inventory and documentation

Important Notes:

• Fully idempotent - can be safely run multiple times without errors
• If package installation fails, the container may need proxy settings configured
• Check /etc/environment and proxy configuration if installation errors occur

Routing Configuration Tools

add_static_route

Adds static routes to container routing tables for custom network topologies.

Parameters:

• container_name: Target container name
• destination_network: Target network in CIDR notation
• gateway_ip: Next-hop gateway IP address
• interface_name: Interface to use for the route

Use Cases:

• L3 domain testing in ContainerLab
• Custom routing policies
• Multi-homed network configurations
• Network segmentation and isolation

check_routes

Retrieves and analyzes the routing table from a container for network troubleshooting.

Parameters:

• container_name: Target container name
• destination_filter: Optional filter for specific destinations (e.g., 'default', '192.168.10.0/24')

Returns:

• Structured Route Data: Parsed route entries with destination, gateway, interface, metric, protocol, and scope
• Raw Output: Complete ip route show command output
• Route Statistics: Total number of routes found
• Filter Information: Applied destination filter details

Use Cases:

• Inter-VLAN Testing: Verify routing between different VLANs and subnets
• Route Validation: Confirm static routes added with add_static_route
• Connectivity Troubleshooting: Understand traffic flow paths in complex topologies
• Network Diagnostics: Debug routing problems and validate configurations
• Topology Analysis: Analyze routing paths for network optimization
• Gateway Verification: Confirm default gateway and specific route configurations

route_delete

Removes static routes from a container's routing table for cleanup and reconfiguration.

Parameters:

• container_name: Target container name
• destination_network: Target network in CIDR notation to remove routes for
• gateway_ip: Optional gateway IP to match for route deletion (if not specified, matches any gateway)
• interface_name: Optional interface name to match for route deletion (if not specified, matches any interface)

Flexible Deletion Options:

• Destination Only: Remove all routes to a specific destination (route_delete("container1", "192.168.10.0/24"))
• Destination + Gateway: Remove route via specific gateway (route_delete("container1", "192.168.10.0/24", "10.0.0.1"))
• Destination + Interface: Remove route via specific interface (route_delete("container1", "192.168.10.0/24", None, "eth1.100"))
• Complete Specification: Remove exact route match (route_delete("container1", "192.168.10.0/24", "10.0.0.1", "eth1.100"))

Use Cases:

• Route Cleanup: Remove obsolete or incorrect static routes after testing
• Configuration Changes: Remove old routes before adding new ones for reconfiguration
• Troubleshooting: Remove conflicting routes that are causing connectivity problems
• Network Reset: Restore default routing behavior by removing custom routes
• Lab Management: Clean up routing tables between different test scenarios
• Error Recovery: Remove routes that were added incorrectly or are causing issues

Security Features

• eth0 Protection: All interface modification tools prevent accidental changes to eth0 (management interface)
• Input Validation: Comprehensive parameter validation and error handling
• Safe Operations: Graceful handling of missing interfaces and existing configurations