ESP32 MCP

Download firmware · Installation · Claude / ChatGPT / Codex · Full setup · Device drivers

Hardware tools, reusable skills and on-device Lua for MCP coding agents.

Connect Codex, Claude or another MCP client to ESP32 over local Wi-Fi or an authenticated outbound relay. Run existing operations, compose saved skills, or upload Lua without rebuilding firmware. The default tools server needs no model key: your MCP client supplies the intelligence.

Board profiles

This project is independent. The K10 adapter retains the companion project's hardware features. Generic profiles do not acquire a camera, microphone or screen automatically. Other boards need a compatible Arduino target and a reviewed adapter/pin map. Compilation is distinct from physical validation: see testing.

Related MCP server: OmniMCP

Execution and persistence

API v3 adds background Lua tasks, status snapshots, task mailboxes and a catalog of 32 concrete device drivers, including NRF24L01+. See drivers and background execution for wiring examples and validation status.

Lua has memory, source, instruction and time limits. GPIO is denied until explicitly allowed with configure_device_pins, within the board profile ceiling. Python excludes arbitrary imports, shell, files and sockets. Neither executor is a hardened hostile-code sandbox. New native drivers still require firmware changes. Execution comparison · Lua API · Python API.

Prebuilt firmware

Download the release firmware ZIP, select the exact board profile and follow binary installation. Public images contain no credentials; configure Wi-Fi/tokens over USB after flashing, without rebuilding. Factory images are for initial installation; app-only updates preserve NVS when the partition layout is unchanged.

Start

1. Install Python 3.11/3.12, VS Code and PlatformIO. Copy include/board_config.example.h to ignored include/board_config.h; enter your Wi-Fi and two independent random tokens.

2. Review MCP_ALLOWED_PINS against your board pinout. Empty means all external pin access is denied.

3. Select the matching environment from the table, build and upload. Chip variants require different binaries; do not flash the default ESP32 image to S3/C3/C6/S2. K10 uses k10, not default esp32dev.

4. Install requirements and configure the MCP client:

python -m venv .venv
.venv/Scripts/python.exe -m pip install -r requirements.txt
$env:ESP_MCP_CONNECTION = 'direct'
$env:ESP_MCP_BOARD_URL = 'http://192.0.2.1:8765'
$env:ESP_MCP_BOARD_TOKEN = 'REPLACE_WITH_BOARD_TOKEN'
.venv/Scripts/python.exe server.py --check

The IP is a documentation placeholder. --check validates configuration without contacting hardware. For bare ESP32 use Codex TOML or Claude JSON. For K10 use Codex K10 or Claude K10, replacing paths and tokens locally. MCP uses stdio; logs go to stderr. Host ports default to 8777/8778. Do not expose unencrypted device HTTP publicly.

Full Russian guide: Installation and connection.

MCP tools

• native_api_reference: get all native function signatures without reading source.

• scan_wifi_networks: scan on the board and return a native job ID.

• configure_device_pins: persist an exact external GPIO allowlist without reflashing.

• hardware_capabilities: inspect the connected board profile before selecting operations.

• execute_device_code(source="return 6 * 7"), then device_code_status(job_id=...): execute Lua on the MCU.

• save_device_script: save source, short command and aliases; optionally install/run on the board.

• list_device_scripts, read_device_script, run_device_script, stop_device_code: control persistent native skills, including reading source back from the device.

• save_device_skill, run_composed_skill, match_saved_command: reuse and parameterize JSON skills without duplicates.

• save_python_skill, run_python_skill, python_skill_status: run restricted laptop programs.

Local save and successful NVS installation are separate outcomes. Installed Lua skills survive reset but do not auto-run at boot. An active job continues after host disconnection until completion/deadline. Four Lua slots and four K10 hardware slots are separate pools sharing one MCU; memory and peripheral contention can reject work.

Optional K10 voice and media

server.py --voice enables A → speak → A capture, local or Groq STT, saved-skill routing and Codex generation. Add --local-stt and install local dependencies for local recognition. Credentials stay on the laptop. The vendor local-ASR wake phrase remains a hardware compatibility constant; the generic core does not depend on it.

K10 preserves local-command priority, transcripts, the green activity overlay, hardware jobs, camera preview, still photos and bounded silent AVI saving. B remains available. No continuous surveillance or video/person analysis is included. Feature matrix.

server.py --gateway-only --profile generic runs an independent owning service. Avoid competing gateways on the same ports. K10 uses --profile k10; generic mode omits camera/voice/display UI tools. Direct-mode photo/video still needs a reachable gateway URL and matching upload token. Cross-network operation uses outbound WSS, one board per gateway.

K10 startup displays the same gray-to-green eye animation as the companion firmware, stage percentages and by vb3227. Headless profiles report initialization on Serial.

Source and checks

server.py                 Public MCP entry
src/core/                 Lua runtime and relay
src/boards/generic/       ESP32 supervisor
src/boards/k10/           K10 hardware/voice/media adapter
include/                  Headers and public configuration template
lib/lua/                  Upstream Lua and provenance
mcp/                      Host tools and optional voice services
skills/                   Saved JSON/Python/Lua programs
config/                   Client templates with placeholders
 docs/                    Setup, APIs and limits
 tests/ and scripts/      Tests and explicit source packaging

python -m pip install -r requirements-dev.txt
python -m unittest discover -s tests -t . -v
python scripts/check_repository.py
python scripts/package_source.py

Packaging explicitly selects sources, excluding credentials, runtime data, captures, caches, firmware and build output. Review the resulting archive. Security · Contributing · Architecture.

Author: vb3227. Original project code is MIT licensed. Bundled components retain their upstream licenses.