ESP32 Control

What ESP32 Control MCP server does

ESP32 Control MCP server exposes operations for an ESP32 device to an MCP-compatible AI client. The device reports whether it is online, its chip information, available heap, and uptime. Agents can also set supported GPIO outputs high or low, read digital pin states, measure analog voltage in millivolts, send a raw AT or application command, and reboot the device.

The repository includes MicroPython firmware for the ESP32 and a Python MCP server. The firmware provides the HTTP endpoint that the server calls. The design supports a device connected locally through its access point or remotely through a configured network address.

How it works

The request path is AI client to MCP server, then to the ESP32 REST API. The server communicates with the device over HTTP, while the AI client communicates with the server through MCP. Local clients can launch the command with stdio transport. A separate HTTP transport is available when an agent needs to reach the MCP server remotely.

The included firmware starts an ESP32 Wi-Fi access point named ESP32-MCP with password 12345678, unless it is configured for station mode in the firmware. The default device endpoint is http://192.168.4.1.

Setup and configuration

Install MicroPython on the ESP32, then upload esp32_firmware/main.py as main.py using a tool such as Thonny or mpremote. After powering the board, configure the device’s network mode as needed.

Install the server with pip install esp32-mcp. Set ESP32_HOST to the ESP32 REST endpoint before running esp32-mcp. ESP32_TIMEOUT controls the request timeout in seconds and defaults to 8. Run without extra transport options for stdio, or use uv run esp32-mcp --transport http --port 8000 for HTTP transport.

Claude Desktop can add the server through its MCP configuration using the esp32-mcp command and ESP32_HOST. Cursor can add it from Settings, MCP, and Add server.

Tools and capabilities

• Check online state, chip details, free heap, and uptime with esp32.status.
• Set a GPIO output high or low with esp32.gpio_set.
• Read a digital pin with esp32.gpio_read.
• Read analog voltage in millivolts with esp32.adc_read.
• Send an AT or application command with esp32.send_command.
• Restart the board with esp32.reboot.

Limitations and notes

By default, GPIO outputs are restricted to pins 2, 4, 5, 18, and 19. Changing the GPIO_OUT setting in the firmware changes that list. The firmware listens on the device’s network, so change the default access-point password before exposing the device beyond a controlled network.

The free offering supports one device and includes the six core tools. Multi-device operation, history, batch control, OTA, and webhooks are listed under the paid Pro plan. The project is licensed under MIT.

The ESP32 Control MCP server requires the ESP32 firmware to be installed and reachable at the configured HTTP address; it does not operate as a standalone simulator.