Ryan Malloy ff138c492e Fix QEMU version detection and remove unsupported ESP32-S2

Sort glob results when auto-detecting QEMU binaries to reliably
pick the newest version. Previously filesystem ordering could select
an older build (8.2.0 instead of 9.0.0), missing ESP32-S3 support.

Remove ESP32-S2 from CHIP_MACHINES — the Espressif QEMU fork has
no esp32s2 machine type.

2026-01-28 16:59:24 -07:00

3.4 KiB

Raw Blame History

MCP ESPTool Server

FastMCP server providing AI-powered ESP32/ESP8266 development workflows through natural language interfaces.

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 mcp-esptool-server

# Or install in project
uv add mcp-esptool-server

Claude Code Integration

# Add to Claude Code
claude mcp add mcp-esptool-server "uvx mcp-esptool-server"

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

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.

3.4 KiB Raw Blame History