esp32_nat_router

This MCP server is implemented as firmware for the ESP32-based NAT router. It exposes a Web UI and a Serial/Remote Console to configure networking between the AP uplink and the WAN uplink (STA or Ethernet). Key capabilities include NAT routing, DHCP reservations, port forwarding, a firewall with ACLs, PCAP streaming, optional WireGuard VPN for upstream traffic, WPA2-Enterprise support to bridge enterprise networks to WPA2-PSK, MQTT Home Assistant telemetry, and an AI-ready MCP Bridge for control via Model Context Protocol. You can manage local clients, view per-client statistics, capture live packets, and remotely administer the device over the network or via a local serial console. The MCP Bridge feature enables integration with AI assistants to issue context-aware commands to the router.

Prerequisites:

• ESP32-based hardware (ESP32 NAT Router compatible boards such as ESP32 or WT32-ETH01) configured for firmware flashing
• USB cable for flashing and a computer with Python/ESP tooling installed as needed

Option A: Flash pre-built binaries

1. Connect the ESP32 NAT Router hardware to your computer via USB.
2. Download the pre-built binary package for your chip variant (ESP32, ESP32-C3, ESP32-C6, ESP32-S3, or WT32-ETH01) from the project wiki/releases.
3. Install esptool if not already installed: python -m pip install esptool
4. Flash the firmware (example for ESP32): esptool.py --chip esp32 --before default_reset --after hard_reset write_flash
   -z --flash_mode dio --flash_freq 40m --flash_size detect
   0x1000 firmware_esp32/bootloader.bin
   0x8000 firmware_esp32/partition-table.bin
   0x10000 firmware_esp32/esp32_nat_router.bin

Option B: Build from source (ESP-IDF)

1. Install ESP-IDF per the official guide and set up the toolchain.
2. Clone the repository and navigate to the ESP32 NAT Router project directory.
3. Build and flash: idf.py set-target esp32 idf.py menuconfig # Enable LWIP IP forwarding, NAT, and related features idf.py build idf.py flash monitor

Post-flash:

• Connect to the router’s AP named ESP32_NAT_Router and open http://192.168.4.1 to configure the upstream network, NAT, and services.
• Alternatively use the Remote Console via TCP as configured in the UI for network-accessible CLI.

Tips and known considerations:

• The router supports multiple advanced features, but RAM on the ESP32 is limited. The maximum concurrent WiFi clients is 8 (5 on ESP32-C3). Enabling Web UI, PCAP, WireGuard, Remote Console, WPA Enterprise, and MQTT together may exhaust available RAM. Check remaining heap in real time and disable features you don’t need.
• WireGuard is optional and can be configured to tunnel upstream traffic with MSS clamping and MTU tuning for reliability.
• WPA2-Enterprise support enables connecting to corporate networks and converting them to WPA2-PSK for simpler devices.
• MQTT Home Assistant integration publishes telemetry and per-client stats with HA auto-discovery.
• MCP Bridge (AI-Ready) enables control from AI assistants via the Model Context Protocol. This is in beta, so expect rapid updates and occasionally breaking changes.
• If using the Serial Console, you can access a full CLI for advanced configuration; the Web UI provides easier day-to-day management.
• For Ethernet uplink (WT32-ETH01), ensure you select the correct hardware variant and PHY wiring as documented in the wiki.