arduino-app-lab-mcp

MCP server for Arduino Lab for MicroPython — the official Arduino IDE for MicroPython boards.

Wraps mpremote and arduino-cli behind a REST/MCP API so an AI agent can list boards, run MicroPython scripts, eval/exec Python, upload/download files, manage the board filesystem, install mip packages, and compile/upload Arduino sketches (including Arduino UNO Q over the network) — all without the IDE open.

arduino-mcp (the companion package) targets the Arduino CLI and IDE 2.0 workflow and can be installed alongside this one for extended functionality. This package is the primary MCP for App Lab IDE usage and UNO Q development.

Install & run

npm install -g arduino-app-lab-mcp
arduino-app-lab-mcp
# → http://127.0.0.1:3095

Or run without installing:

npx arduino-app-lab-mcp

Requires Python + mpremote:

pip install mpremote

arduino-cli is auto-downloaded on npm install via the postinstall script — no manual setup needed.

API

All responses: { "ok": true, "requestId": "…", "action": "…", … } or { "ok": false, "error": "…" }.

MicroPython / mpremote

| Method | Path | Body / Params | Description | |--------|------|---------------|-------------| | GET | /health | — | Status: mpremote + arduino-cli versions | | GET | /actions | — | List all supported actions | | GET | /boards | — | Enumerate connected boards | | POST | /run | { "file": "main.py", "device": "auto" } | Run script from workspace on board | | POST | /exec | { "code": "print(42)", "device": "auto" } | Execute Python code on board | | POST | /eval | { "expression": "1+1", "device": "auto" } | Evaluate expression, return result | | POST | /upload | { "file": "main.py", "dest": ":main.py" } | Copy file workspace → board | | POST | /download | { "file": "main.py" } | Copy file board → workspace | | GET | /ls | ?dir=/&device=auto | List board filesystem | | DELETE | /rm | { "file": "old.py" } | Remove file from board | | POST | /reset | { "hard": false } | Soft or hard reset | | POST | /install | { "package": "aioble" } | Install mip package |

Arduino CLI (sketch workflow)

| Method | Path | Body | Description | |--------|------|------|-------------| | POST | /sketch | { "name": "Blink", "code": "…" } | Create a new .ino sketch | | GET | /sketch/:name | — | Read sketch source | | GET | /sketches | — | List all sketches in workspace | | POST | /validate | { "sketch": "Blink", "fqbn": "…" } | Syntax-check without uploading | | POST | /build | { "sketch": "Blink" } | Compile + export binaries | | POST | /upload_sketch | { "sketch": "Blink", "port": "192.168.1.63" } | Compile + upload (network OTA for UNO Q) | | POST | /reset_to_bootloader | { "port": "COM4" } | 1200-baud touch for DFU bootloader |

Device path

"device": "auto" (default) lets mpremote auto-detect the first board. Or specify explicitly:

• Windows: "device": "COM5"
• Linux/Pi: "device": "/dev/ttyACM0"
• macOS: "device": "/dev/cu.usbmodem14101"

UNO Q (Arduino:Zephyr)

The default FQBN is arduino:zephyr:unoq. Upload via network IP (OTA):

curl -X POST http://127.0.0.1:3095/upload_sketch \
  -H "Content-Type: application/json" \
  -d '{"sketch":"Blink","port":"192.168.1.63"}'

Environment

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3095 | HTTP port | | APPLAB_DEVICE | auto | Serial port for mpremote | | APPLAB_WORKSPACE | ./workspace | Local workspace directory | | MPREMOTE_BIN | mpremote | Path to mpremote binary | | ARDUINO_CLI_BIN | auto | Path to arduino-cli (auto-downloaded) | | ARDUINO_FQBN | arduino:zephyr:unoq | Default board FQBN | | ARDUINO_UPLOAD_PORT | — | Network IP for UNO Q OTA upload | | ARDUINO_AUTO_INSTALL_CORE | 1 | Auto-install missing arduino-cli cores | | ARDUINO_COMPILE_TIMEOUT_MS | 600000 | Compile timeout (ms) | | APPLAB_RUN_TIMEOUT_MS | 30000 | mpremote run timeout (ms) | | APPLAB_EXEC_TIMEOUT_MS | 10000 | mpremote exec/eval timeout (ms) | | LOG_REQUESTS | 0 | Set 1 to log every request |

Copy .env.example to .env to configure locally.

Docker

docker build -t arduino-app-lab-mcp:latest .
docker run --rm --network host \
  -e PORT=3095 \
  --device /dev/ttyACM0 \
  -v $(pwd)/workspace:/workspace \
  arduino-app-lab-mcp:latest

Boards supported

Arduino UNO Q (Zephyr/Linux), UNO R4 Minima/WiFi, Nano RP2040 Connect, Nano 33 BLE, Portenta H7, GIGA R1, Raspberry Pi Pico/W, ESP32, ESP8266, STM32 — any board running MicroPython that mpremote can connect to.

Related

• arduino-app-lab-mcp-micropy — Sister package: direct serial REPL via micropython.js (no mpremote needed). More granular filesystem ops, stateful connection pool. Port 3096.
• arduino-mcp — MCP server for Arduino CLI and IDE 2.0. Install alongside for extended CLI/IDE 2.0 functionality.

Author

Eoin Jordan — eoinjordan.github.io — for more projects, related work, or suggestions.

License

MIT © Eoin Jordan