# Esp32 Loop

> Fast flash→observe→iterate loop between ESP32 boards and an AI agent.

- **Type:** MCP server
- **Install:** `agentstack add mcp-nevescloud-esp32-loop`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nevescloud](https://agentstack.voostack.com/s/nevescloud)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [nevescloud](https://github.com/nevescloud)
- **Source:** https://github.com/nevescloud/esp32-loop

## Install

```sh
agentstack add mcp-nevescloud-esp32-loop
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# esp32-loop

[](LICENSE)

**Host-side eyes and hands on a *running* ESP32.** Flashing firmware is the part every
tool has; the edge is everything *after boot* — a real host-side BLE client
(`gatt`/`read`/`sub`/`send`) plus per-board transport modeling, so an agent can observe
and command a board that's actually running, across native-USB or any UART bridge (a
native-USB C3, an FTDI- or CP2102-bridged classic ESP32).

```
   ┌─▶ write ─▶ flash ─▶ observe ─▶ control ─┐
   └─────────────── iterate ◀ ───────────────┘
```

It runs the whole arc — so an agent goes from "I want an ESP32 to do X" to a running,
commandable device on its own. No IDE, no interactive monitor, no hand-written IDF
boilerplate.

```
esp32loop detect                        # what's plugged in: board, transport, chip

esp32loop new                     # scaffold a firmware project from a template
esp32loop flash                  # build + upload (scaffold, example, any IDF tree)

esp32loop watch                  # capture serial as text — not an interactive monitor
esp32loop scan                          # BLE scan — what's advertising?
esp32loop status                 # one-call ground-truth: plugged in? advertising? drivable? telemetry
esp32loop gatt                   # connect: list services + characteristics
esp32loop read                   # connect: read a characteristic (telemetry)
esp32loop sub                    # connect: stream notifications (live state)
esp32loop send       # connect: drive a pin
esp32loop wifi       # connect: provision WiFi over BLE, watch it join
```

## Quickstart

Requires [`uv`](https://docs.astral.sh/uv/) and [ESP-IDF](https://docs.espressif.com/projects/esp-idf/)
(v5.5) at `~/esp/esp-idf` — the CLI auto-sources it.

```
uv run esp32loop detect
uv run esp32loop new blinky --template ble_control   # your own firmware, ready to edit
uv run esp32loop flash c3_supermini --project blinky --watch
uv run esp32loop send c3_supermini 8 1               # connect over BLE, drive a pin
```

## Boards

Each board is one `boards/.toml` declaring its chip target, transport, console
location, and download quirks — the single source of truth. Ships with:

| board | chip | transport | console | flashing |
|-------|------|-----------|---------|----------|
| `c3_supermini` | esp32c3 | native USB | native USB | one cable, auto-reset |
| `esp32cam` | esp32 | UART bridge (FTDI) | UART0 | auto-reset (RTS→EN) |
| `esp32_devkit` | esp32 | UART bridge (CP2102) | UART0 | auto-reset, USB-C |

These cover both transports — a harness that handles native-USB *and* external UART
bridges (FTDI, CP2102, …) generalizes to most ESP-IDF boards. Add one by dropping a new
`.toml`; no code change.

## Authoring firmware

Two bundled examples double as templates: **`ble_control`** (control + telemetry over a
BLE GATT service — what `gatt`/`read`/`sub`/`send` drive) and **`wifi_provision`** (boots
with no WiFi config and takes its credentials over BLE, so `wifi` configures the network
without a flash-time secret — put the creds in a gitignored `.env` (copy
`.env.example`), read from `ESP32LOOP_WIFI_SSID` / `ESP32LOOP_WIFI_PASSWORD`, never in
the repo). `new` forks one into a ready-to-flash project — write only the logic:

```
uv run esp32loop new blinky --template ble_control
# edit blinky/main/blinky_main.c, then:
uv run esp32loop flash  --project blinky --watch
```

Or point `flash` at any existing IDF project:

```
uv run esp32loop flash  --project /path/to/firmware
```

## Agent integration

The repo ships a Claude Code skill (`.claude/skills/esp32-loop/`) that teaches an agent
the whole loop — scaffold, flash, observe, control — and the per-board traps, so it
grounds its claims in `detect`/`watch`/`scan` output instead of guessing. The aim is an
agent that can take an ESP32 and prototype on it end to end, on its own.

For non-Bash clients, the runtime verbs (`scan`/`status`/`gatt`/`read`/`sub`/`send`/`wifi`)
are also exposed as an MCP server: `uv run --extra mcp esp32loop-mcp`.

## License

[MIT](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nevescloud](https://github.com/nevescloud)
- **Source:** [nevescloud/esp32-loop](https://github.com/nevescloud/esp32-loop)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-nevescloud-esp32-loop
- Seller: https://agentstack.voostack.com/s/nevescloud
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.