ESP32 NAT Router MCP Bridge

关键词

ESP32网络网关自动化运维远程控制AI 集成

使用说明（Markdown 格式）

  • 项目简介

    • 该仓库包含一个 MCP 服务器实现，用于通过 MCP 客户端对 ESP32 NAT Router 进行远程管理。核心通过一个 Python 模块 esp_nat_bridge.py 实现，使用 fastmcp 框架定义工具（Tools），从而将路由器的功能暴露给 LLM/自动化代理等客户端。

  • 主要功能点

    • MCP 服务端：实现了基于 JSON-RPC 的 MCP 服务（工具接口，便于 LLM 调用）。
    • 工具集合（Tools）：提供 show_status、show_config、show_mappings、get_heap_info、get_version、get_byte_counts、reset_byte_counts、wifi_scan 等多种路由器状态与配置相关操作。
    • 安全与连接：通过远程控制台（ESP32 的 Telnet/TCP 界面）实现对路由器的实际命令执行，桥接层负责在 MCP 客户端和 ESP32 远程控制台之间进行通信。
    • 传输协议支持：支持 stdio、SSE、streamable-http 等传输方式，方便在不同环境中接入 MCP 客户端。
    • 适配生态：README 中明确包含 MCP Bridge（AI-Ready）功能描述，适合与 AI 助手进行联动。

  • 安装步骤

    • 确保 Python 运行环境与依赖：
      • 安装 Python 3.x
      • 安装依赖：fastmcp、telnetlib3
    • 获取代码后在服务器上执行 esp_nat_bridge.py
    • 运行示例（具体命令见下方“服务器配置与启动参数”部分）：将根据需要选择传输模式运行

  • 服务器配置（MCP 客户端需要的配置示例，JSON 形式）

    • server_name: ESP32 NAT Router MCP Bridge
    • command: python esp_nat_bridge.py
    • args: ["--transport", "stdio"] 或 ["--transport", "streamable-http", "--port", "8000"]
    • env:
      • ESP_NAT_HOST: "192.168.4.1" (ESP32 NAT Router 的管理端地址)
      • ESP_NAT_PORT: "2323" (远程控制台端口)
      • ESP_NAT_PASSWORD: "" (如果远程控制台需要认证，可配置密码)
    • 注释说明：
      • transport 指定 MCP 传输方式，stdio 适合直接 CLI 客户端接入，streamable-http 适合通过 HTTP 传输接入 MCP 客户端。
      • host/port/password 与实际设备网络配置保持一致，以确保 MCP 服务端能正确连接 ESP32 的远程控制台。

  • 基本使用方法

    • 启动 MCP Bridge 服务后，使用 MCP 客户端连接该服务器，调用内部定义的工具接口（如 show_status、set_sta、portmap 等），获取路由器状态、执行配置变更、查询日志等。工具输出会以文本形式返回，便于将结果整合进你的对话/自动化工作流。
    • 如需在生产环境中自动化调用，建议使用支持 JSON-RPC 的 MCP 客户端以便与工具进行清晰、可控的交互。

  • 运行与调试要点

    • 确保 ESP32 NAT Router 处于可访问状态，尤其远程控制台端口（默认 2323）和网络连通性。
    • 若 ESP32 的远程控制台要求密码，请在 ESP_NAT_PASSWORD 环境变量中设置正确的密码。
    • 根据硬件资源限制，注意启用的特性数量（如 PCAP、MQTT、Web UI 等会占用内存），避免超出设备资源导致服务不可用。

  • 注意事项

    • 该实现以桥接方式工作，将 MCP 客户端请求转发到 ESP32 的远程控制台执行命令，结果输出以文本形式返回。
    • 由于远程控制台本身为未加密的明文 TCP 连接，请在受信任网络中使用，必要时在网络层增加加密与鉴权机制。

服务器信息

访问项目