mcesptool

FastMCP server for ESP32/ESP8266 development workflows via Model Context Protocol.

Features

• Chip Control: Advanced ESP device detection, connection, and control
• Flash Operations: Comprehensive flash memory management with safety features
• Security Management: ESP security features including secure boot and flash encryption
• Production Tools: Factory programming and batch operations
• Middleware System: Universal CLI tool integration with bidirectional MCP communication
• ESP-IDF Integration: Host application support for hardware-free development
• QEMU Emulation: Virtual ESP32 devices for testing without physical hardware

Quick Start

Installation

# Install with uvx (recommended)
uvx mcesptool

# Or install in project
uv add mcesptool

Claude Code Integration

# Add to Claude Code
claude mcp add mcesptool "uvx mcesptool"

Development Setup

# Clone and setup
git clone <repository>
cd mcp-esptool
make dev

# Run development server
make run-debug

# Run tests
make test

Architecture

The server implements a component-based architecture with middleware for CLI tool integration:

• Components: Specialized modules for different ESP development workflows
• Middleware: Universal pattern for intercepting and redirecting CLI tool output to MCP context
• Configuration: Environment-based configuration with auto-detection
• Production Ready: Docker support with development and production modes

Components

• ChipControl: Device detection, connection management, reset operations
• FlashManager: Flash operations with verification and backup
• PartitionManager: Partition table management and OTA support
• SecurityManager: Security features and eFuse management
• FirmwareBuilder: ESP-IDF integration and binary operations
• OTAManager: Over-the-air update workflows
• ProductionTools: Factory programming and quality control
• Diagnostics: Memory dumps and performance profiling
• QemuManager: QEMU-based ESP32 emulation with download mode, efuse, and flash support

Flash Operations

Advanced flash management tools for efficient firmware deployment:

Tool	Description
esp_flash_firmware	Flash a single binary to device
esp_flash_multi	Flash multiple binaries at different addresses in one operation
esp_verify_flash	Verify flash contents match a file without re-flashing
esp_flash_read	Read flash memory to a file
esp_flash_erase	Erase flash regions
esp_flash_backup	Create complete flash backup

Multi-File Flashing

Flash bootloader, partition table, and app in a single operation:

esp_flash_multi(
    files=[
        {"address": "0x0", "path": "bootloader.bin"},
        {"address": "0x8000", "path": "partitions.bin"},
        {"address": "0x10000", "path": "app.bin"}
    ],
    port="/dev/ttyUSB0",
    verify=True
)

RAM Loading (Development Iteration)

Test firmware changes without wearing out flash:

Tool	Description
esp_elf_to_ram_binary	Convert ELF to RAM-loadable binary
esp_load_ram	Load and execute binary in RAM
esp_serial_monitor	Capture serial output from device

Workflow

# 1. Build your ESP-IDF project
idf.py build

# 2. Convert ELF to RAM binary
esp_elf_to_ram_binary(elf_path="build/my_app.elf", chip="esp32s3")

# 3. Load to RAM and execute (no flash wear!)
esp_load_ram(binary_path="my_app-ram.bin", port="/dev/ttyUSB0")

# 4. Capture output
esp_serial_monitor(port="/dev/ttyUSB0", duration_seconds=10)

Note: RAM loading requires ELFs built without secure boot (CONFIG_SECURE_BOOT=n). Some PlatformIO defaults may be incompatible.

QEMU Emulation

Run virtual ESP32 devices without physical hardware. Requires Espressif's QEMU fork:

# Install via ESP-IDF tools
source /path/to/esp-idf/export.sh
python3 $IDF_PATH/tools/idf_tools.py install qemu-xtensa qemu-riscv32

The server auto-detects QEMU binaries from ~/.espressif/tools/. Once available, five tools are exposed:

Tool	Description
esp_qemu_start	Launch a virtual ESP device (supports esp32, esp32s3, esp32c3)
esp_qemu_stop	Stop a running instance
esp_qemu_list	List all running instances
esp_qemu_status	Detailed instance info
esp_qemu_flash	Write firmware to a virtual device's flash

Virtual devices appear in esp_scan_ports alongside physical hardware, connected via socket://localhost:<port>.

Configuration

Configure via environment variables or .env file:

ESPTOOL_PATH=esptool
ESP_DEFAULT_BAUD_RATE=460800
ESP_IDF_PATH=/path/to/esp-idf
MCP_ENABLE_PROGRESS=true
PRODUCTION_MODE=false

Docker

# Development with hot reload
make docker-up

# Production deployment
DOCKER_TARGET=production make docker-up

License

MIT License - see LICENSE file for details.