convez.ai
MCP ServerAutomaçãoAvançado
jonasneves

ESP32 MCP — Plano de Controle Remoto via WiFi

jonasneves/esp32-mcp

Controle remoto de ESP32 via MCP, sem IP público necessário

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que expõe um ESP32 para controle remoto via WiFi através de uma arquitetura de rendezvous em Cloudflare Workers. O microcontrolador se conecta via WebSocket a um Durable Object que funciona como relé, permitindo que clientes MCP autenticados (Claude Desktop, APIs) controlem pinos GPIO e executem comandos arbitrários. Ideal para robotics, IoT e prototipagem remota onde o dispositivo não possui IP público.

Instalação

$npx convez-ai jonasneves/esp32-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Robotics remoto com telemetria em tempo real
  • IoT e automação de dispositivos sobre WiFi
  • Prototipagem de hardware assistida por IA

Veredito

Implementação técnica sólida de um padrão push (rendezvous) para contornar o problema de dispositivos sem IP público. O design é genérico e bem documentado, mas exige familiaridade com MCP, WebSockets, Durable Objects e eletrônica. Produção requer hardening adicional de autenticação por dispositivo.

README

A tradução para o português deste README ainda está na fila.

esp32-mcp

A remote MCP control plane for an ESP32 over WiFi. An LLM client (claude.ai, Claude Desktop, any MCP client) connects to one authenticated endpoint and gets hands on the board — set a pin, read telemetry, send a command — from anywhere.

The board has WiFi but no public address, and the Worker has no radio, so the board dials out: it opens one WebSocket to the relay and keeps it. The Worker is a rendezvous, not a poller.

LLM client ──MCP (HTTP, OAuth)──► /mcp  ┐
                                        │  Cloudflare Worker
   board ──WSS (device token)──► /link  ┘   ├─ EspMcp        Durable Object (MCP session)
                                            └─ BoardLink     Durable Object (holds the board's WSS)
                                                  │ cmd ↓ / ack ↑ / telemetry ↑
                                                  ▼
                                              ESP32 (robot)

This is the cloud consumer of esp32-loop — the bench tool that flashes the board and provisions its WiFi over BLE. esp32-loop owns the local write→flash→observe→control loop; esp32-mcp re-exposes the control + observe half to remote LLMs once the board is on the network. The verb surface is the board-reachable subset (no BLE/USB discovery — that's bench-local).

Tools

ToolDoes
statusIs the board dialed in? Last-seen + its hello info.
telemetryLatest JSON snapshot the board pushed.
gpio(pin, level)Set a GPIO pin (0/1), await the board's ack.
command(op, args)Any board-specific op (e.g. a robot's drive), await ack.

Generic by design — the board (or a robot layer on top) maps its own semantics onto gpio/command.

Auth

  • Humans → OAuth, GitHub as the upstream IdP, restricted to ALLOWED_GITHUB_LOGINS. It controls physical hardware; keep the list tight.
  • The board → a DEVICE_TOKEN on /link (a microcontroller can't run a browser OAuth flow) — a wrangler secret, never committed. Per-board keys are the planned next step.

Wire protocol (DO ↔ board)

Small JSON frames over the WSS link (see src/types.ts):

board → relay   {"t":"hello","board":"robot","fw":"..."}
                {"t":"telemetry","data":{...},"ts":1234}
                {"t":"ack","id":"<uuid>","ok":true,"result":{...}}
relay → board   {"t":"cmd","id":"<uuid>","op":"gpio","pin":2,"level":1}

The board keeps one socket open, pushes telemetry, and acks each cmd by id.

Setup

npm install
wrangler kv namespace create OAUTH_KV     # paste the id into wrangler.jsonc
npm run oauth-app                         # opens GitHub's New OAuth App form, prefilled
cp .dev.vars.example .dev.vars            # fill in the Client ID/secret + a DEVICE_TOKEN

npm run oauth-app prefills name/homepage/callback; you still generate the client secret by hand. For a local-dev app, override the callback: npm run oauth-app -- --callback http://localhost:8787/callback. Then:

npm run dev                               # relay on http://localhost:8787

# in another shell — a simulated board, no hardware needed:
TOKEN=<your DEVICE_TOKEN> npm run fake-board

# point an MCP client at http://localhost:8787/mcp, or inspect it:
npx @modelcontextprotocol/inspector@latest

Call status → online; gpio 2 1 → the fake board logs the command and acks.

Deploy:

wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put DEVICE_TOKEN
wrangler deploy

Point neves.cloud/esp32-mcp at the Worker with a route or custom domain.

Firmware contract

Any board that (1) joins WiFi — esp32-loop's wifi_provision example hands creds over BLE — and (2) opens a WSS to wss://<host>/link?board=<id>&token=<DEVICE_TOKEN> speaking the frames above is controllable. scripts/fake-board.mjs is the reference implementation; the on-chip version is the next build.

Ver o original no GitHub

Bom para

Relacionados