ESP32 MCP Server

Control your ESP32 running MicroPython via USB serial — directly from any MCP-compatible AI assistant (Claude Desktop, opencode, etc.).

Requirements

• Python 3.10+
• ESP32 with MicroPython firmware (flashed via USB)
• USB cable (data-capable)

Install

# Clone and enter the project
git clone <your-repo>
cd mcp-esp32

# Run with uv (recommended — auto-installs dependencies)
uv run python3 server.py

# Or with pip
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
python3 server.py

Configuration

Set these environment variables to match your setup:

Variable	Default	Description
ESP32_PORT	/dev/cu.usbserial-2120	Serial port for your ESP32
ESP32_BAUD	115200	Baud rate (MicroPython default)
ESP32_TIMEOUT	5	REPL command timeout in seconds

Example:

export ESP32_PORT=/dev/ttyUSB0
export ESP32_BAUD=115200
uv run python3 server.py

Tip: On Linux the port is usually /dev/ttyUSB0 or /dev/ttyACM0.
On macOS it's /dev/cu.usbserial-* or /dev/cu.usbmodem*.
On Windows it's COM3, COM4, etc.

Usage with AI Assistants

opencode

Add to your opencode.json:

{
  "mcp": {
    "esp32": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/path/to/mcp-esp32", "python3", "server.py"],
      "enabled": true
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "esp32": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-esp32", "python3", "server.py"]
    }
  }
}

Tools

Tool	Description
exec	Execute Python code on ESP32 REPL
gpio_set	Set GPIO pin HIGH(1), LOW(0), or TOGGLE(2)
gpio_read	Read GPIO pin value (0 or 1)
neopixel	Set WS2812 RGB LED color
info	Show chip info: model, frequency, flash, memory
adc_read	Read analog voltage from an ADC pin
wifi_config	Connect ESP32 to a WiFi network
file_list	List files on ESP32 filesystem
file_read	Read a file from ESP32
file_write	Write or overwrite a file on ESP32
file_delete	Delete a file on ESP32

First-Time Setup

1. Flash MicroPython to your ESP32:

   # Erase
   esptool.py --chip esp32s3 -p /dev/ttyUSB0 erase-flash
   
   # Flash
   esptool.py --chip esp32s3 -p /dev/ttyUSB0 write-flash 0x0 ESP32_GENERIC_S3-*.bin

2. Find your serial port (varies by OS):

   # macOS
   ls /dev/cu.usb*
   
   # Linux
   ls /dev/ttyUSB* /dev/ttyACM*
   
   # Windows (in PowerShell)
   [System.IO.Ports.SerialPort]::getportnames()

3. Set ESP32_PORT and start the server.

License

MIT