Building an MCP Server for ESP32 Microcontrollers

01 The Hardware Gap

Modern agent frameworks are remarkably good at manipulating code, calling REST APIs, and generating text. But the moment you ask an AI model to read a physical voltage from a battery sensor, check an analog signal, or toggle a high-speed relay, the software abstraction falls apart.

To solve this, we implemented an open-source Model Context Protocol (MCP) server that bridges directly to ESP32 microcontrollers over USB CDC-ACM and Bluetooth Low Energy (BLE).

02 Protocol Framing & Architecture

The client communicates with the host daemon using standard JSON-RPC 2.0 stdio framing. The daemon then serializes tool requests into compact binary or 115200-baud newline-delimited command packets sent to the ESP32:

Figure 02 — Model Context Protocol to ESP32 Hardware Execution Pipeline.

03 C++ Firmware Implementation

The firmware runs FreeRTOS with a dedicated serial dispatcher task on Core 1 to avoid blocking ADC sampling routines on Core 0:

ESP32 C++ DISPATCHER (main.cpp)

void handle_mcp_cmd(const char* line) {
    StaticJsonDocument<256> doc;
    DeserializationError err = deserializeJson(doc, line);
    if (err) { Serial.println("{"error":"bad_json"}"); return; }

    const char* method = doc["method"];
    if (strcmp(method, "read_adc") == 0) {
        int pin = doc["params"]["pin"];
        uint32_t val = analogReadMilliVolts(pin);
        Serial.printf("{"result":{"pin":%d,"mv":%lu}}
", pin, val);
    }
}

04 ESP-IDF Compilation & Flash

Compiling the firmware directly from Termux using native LLVM cross-compilation:

TERMUX — idf.py flash /dev/ttyUSB0

$ idf.py -p /dev/ttyUSB0 flash monitor

[ESP-IDF] Chip is ESP32-D0WD-V3 (revision v3.1) [ESP-IDF] Crystal is 40MHz [ESP-IDF] MAC: 24:6f:28:90:1a:04 [FLASH] Writing at 0x00010000... (100 %) [FLASH] Hash of data verified. [MONITOR] FreeRTOS Core 0: ADC calibrated via eFuse Vref. [MONITOR] MCP Serial Dispatcher listening on USB CDC-ACM...

05 MCP Tool Call Execution

When an AI agent executes esp32_read_adc(channel=34), the MCP server dispatches and receives the real-time physical metric:

JSON-RPC tools/call: esp32_read_adc

SUCCESS

{
  "tool": "esp32_read_adc",
  "arguments": { "channel": 34 },
  "response": {
    "millivolts": 3284.5,
    "resolution": "12-bit SAR",
    "status": "verified"
  }
}