esp32-mcp

An MCP server that gives an AI agent control of an ESP32: relays, GPIO pins and analog sensors. The Python side has no dependencies and implements the MCP stdio protocol by hand. The board runs a single Arduino sketch and speaks JSON over HTTP.

AI agent  <-- stdio, JSON-RPC 2.0 -->  esp32-mcp  <-- HTTP, JSON -->  ESP32 firmware

I built this because most "AI controls hardware" demos hide a cloud service in the middle. Here the agent talks to a process on your machine, that process talks to a board on your LAN, and nothing leaves the network.

Status

v0.1.0. The whole path works end to end against a simulated board: handshake, tool discovery, relay switching, sensor reads and GPIO reads and writes. The test suite runs without hardware. The sketch compiles for esp32:esp32:esp32 with arduino-cli 1.4.1 and ESP32 core 3.3.12 (74% flash, 15% RAM). CI does not compile the sketch yet, see Deferred.

Related MCP server: ESP32 MCP Server

What is in the box

Install

git clone https://github.com/StefanYasin/esp32-mcp.git
cd esp32-mcp
python -m pip install -e .

Python 3.9 or newer. There are no runtime dependencies.

Try it without hardware

python scripts/demo.py --fake

That starts the built in simulator, spawns esp32-mcp as a real subprocess and prints the full JSON-RPC exchange: initialize, tools/list, then calls to esp32_health, esp32_read_sensors, esp32_set_relay, esp32_gpio_write and esp32_gpio_read.

Flash the firmware

1. Install the ESP32 board package in the Arduino IDE (Boards Manager -> esp32 by Espressif).

2. Open firmware/esp32_mcp/esp32_mcp.ino.

3. Edit the CONFIG block at the top: WiFi credentials, API_TOKEN, the relay table, the analog sensor table and the GPIO allow list.

4. Select ESP32 Dev Module, upload, then open the serial monitor at 115200 baud.

5. Note the IP address it prints, or use the mDNS name http://esp32-mcp.local.

curl http://esp32-mcp.local/health
curl -X POST http://esp32-mcp.local/relay/1/on
curl "http://esp32-mcp.local/gpio?pin=2&value=1"

The same thing from the command line, which is the path I used to check the sketch:

arduino-cli core install esp32:esp32
arduino-cli compile --fqbn esp32:esp32:esp32 firmware/esp32_mcp
arduino-cli upload --fqbn esp32:esp32:esp32 -p COM5 firmware/esp32_mcp

Swap COM5 for your port. Wiring, pin tables and the safety notes are in docs/wiring.md.

Connect an MCP client

Point the client at the esp32-mcp executable and give it the board URL. This is the Claude Desktop shape; other clients use the same command and env fields.

{
  "mcpServers": {
    "esp32": {
      "command": "esp32-mcp",
      "env": {
        "ESP32_MCP_URL": "http://192.168.1.42",
        "ESP32_MCP_TOKEN": ""
      }
    }
  }
}

If you installed into a virtualenv, use the absolute path to the esp32-mcp executable in that venv.

Environment variables:

Flags --url, --token, --timeout and --verbose override the environment. Logs go to stderr so they never corrupt the protocol stream.

Tools

Agents call esp32_health first to learn which relays and pins exist. Bad arguments come back as a tool result with isError: true and a message that says what to fix. An unknown tool name is a JSON-RPC -32602 error, which is what the MCP spec asks for.

Only pins in the firmware allow list can be touched. The default list leaves out the flash pins and the strapping pins.

HTTP API on the board

The server and the firmware share this contract. It is small on purpose so the sketch stays readable.

Errors use the HTTP status plus {"ok":false,"error":"..."}: 400 for bad parameters, 401 for a bad token, 403 for a pin outside the allow list, 404 for an unknown relay or route, 405 for the wrong method.

Protocol details

The MCP stdio transport is newline delimited JSON-RPC 2.0, one message per line, UTF-8. This server implements:

• initialize with protocol version 2024-11-05, tools capability and server instructions

• notifications/initialized

• ping

• tools/list

• tools/call

Anything else returns -32601 Method not found. Malformed JSON returns -32700 and the stream stays open. Notifications never get a response.

Tests

python -m pytest

88 tests covering the JSON-RPC layer, tool schemas and dispatch, the HTTP client, the simulator contract and the real subprocess stdio transport. No hardware and no network access required; the simulator binds to 127.0.0.1 on a random port.

There is also a compatibility check against the official MCP Python SDK, which is a separate optional install:

python -m pip install mcp
python scripts/interop_check.py

It starts the simulator, spawns the server through the SDK stdio client and checks the handshake, the tool list, a successful relay call and a rejected pin. I ran it against mcp 2.3.0 and it passes. It is not part of CI because the SDK would be a heavy dev dependency.

Security

The board API is plain HTTP with an optional shared token. That is fine on a trusted LAN and wrong on the public internet. Do not port forward the ESP32, and do not put this behind a public reverse proxy without TLS and real authentication.

Relays can switch mains voltage. Use an opto-isolated relay module, keep the mains side away from the logic side, and read docs/wiring.md before connecting anything.

Deferred

• TLS and per client credentials

• PWM and analog writes, servo control

• Sensor drivers (DHT22, DS18B20, I2C) beyond the internal temperature and raw ADC channels

• OTA firmware updates

• A sketch compile job in CI. The ESP32 core is about a 1 GB download, so for now the check is a local compile

• Newer MCP protocol revisions, the server pins 2024-11-05 for now

• An interop job in CI against the official MCP SDK, the check currently runs by hand

License

MIT. See LICENSE.

Built by Stefan Yasin (https://stefanyasin.github.io/)