ESP32MCPServer

The ESP32 MCP Server exposes a standard MCP interface over WebSocket using JSON-RPC 2.0. Once flashed and running, it hosts a WebSocket endpoint at ws://<ESP32_IP>:9000 where AI agents or automation tooling can query real-world sensor data. Through this server you can discover resources (I2C sensors, GPS data via NMEA 0183, NMEA 2000 / CAN frames, and OBD-II data), subscribe to updates, and issue read or control commands. The architecture provides a dashboard served from flash at http://<IP>/app for local monitoring, including a sensor tester, metrics, logs, and an interactive MCP console. Tools available include: I2C sensor drivers (BME280, MPU6050, ADS1115, SHT31, BH1750, INA219) with auto-scan capabilities; NMEA 0183 parsing for GPS data; NMEA 2000 / CAN parsers for position, heading, speed, depth and environmental data; and OBD-II CAN decoding. You can also perform time-bounded serial or CAN reads and receive JSON-formatted outputs, with metrics like uptime, heap usage, and RSSI exposed for monitoring.

Prerequisites:

• An ESP32-S3 development board (ESP32-S3-DevKitC-1 or compatible)
• PlatformIO Core installed, or PlatformIO IDE
• Optional: USB-to-serial adapter for flashing and serial monitoring

Steps:

1. Prepare your ESP32 development environment

   • Install PlatformIO: https://platformio.org/install

2. Get the firmware sources

   • Clone the repository: git clone https://github.com/navado/ESP32MCPServer.git
   • Navigate: cd ESP32MCPServer

3. Build and flash firmware to ESP32-S3

   • Open a terminal and run:
     • pio run -e esp32-s3-devkitc-1
     • pio run -t upload -e esp32-s3-devkitc-1

4. Optional: Upload web assets to LittleFS (recommended for serving the web dashboard)

   • pio run -t uploadfs -e esp32-s3-devkitc-1

5. Monitor serial output and confirm networking

   • pio device monitor --baud 115200

6. Connect a MCP client

   • After the device boots and connects to WiFi, it will broadcast a WebSocket MCP endpoint at ws://<ESP32_IP>:9000. Use the MCP API (initialize, resources/list, resources/read, resources/subscribe) to interact with sensors and buses.

Note: If you are using Docker as the deployment method, ensure Docker is installed and you run with network access to your ESP32 device on the same network.

Tips and common issues:

• Ensure the ESP32 has network access and can reach the AP. The WebUI is served from flash; use http://<IP>/app after first-run.
• If LittleFS content is not served, re-run the uploadfs step to push assets to flash.
• For NMEA 0183 data, verify the GPS/chart plotter wiring and baud rate; mismatch may yield no data until the correct UART is configured in the MCP server.
• CAN bus requires proper transceivers and baud rate settings (NMEA 2000 at 250 kbps, OBD-II at 500 kbps); configure the CANBusReader accordingly.
• When using Docker deployment, expose port mappings if you need to access the MCP WebSocket and HTTP endpoints from outside the host.
• In environments with limited memory, monitor Metrics to ensure the device has enough heap; adjust sampling rates if necessary.