Configuration

mcesptool is configured through environment variables. All settings have sensible defaults and can be overridden individually. The server loads configuration at startup from ESPToolServerConfig, which reads environment variables and auto-detects paths where possible.

---

Core Settings

Variable	Default	Description
ESPTOOL_PATH	esptool	Path or command name for the esptool binary. Set this if esptool is not on your PATH or you want to use a specific version.
ESP_IDF_PATH	(auto-detect)	Path to the ESP-IDF installation directory. Auto-detected from ~/esp/esp-idf, /opt/esp-idf, or /usr/local/esp-idf if not set.
MCP_PROJECT_ROOTS	(auto-detect)	Colon-separated list of directories to scan for ESP projects. Auto-detects from ~/esp_projects, ~/Arduino, ~/Documents/Arduino, and /workspace/projects.

Tip

MCP_PROJECT_ROOTS uses colon (:) as the separator, matching the PATH convention:

MCP_PROJECT_ROOTS=/home/user/esp_projects:/home/user/arduino_projects

---

Communication Settings

Variable	Default	Description
ESP_DEFAULT_BAUD_RATE	460800	Default serial baud rate for device connections. Valid values: 9600, 57600, 115200, 230400, 460800, 921600. Unusual values produce a warning but are not rejected.
ESP_CONNECTION_TIMEOUT	30	Connection timeout in seconds. Must be between 5 and 300.
ESP_ENABLE_STUB_FLASHER	true	Load the ROM bootloader stub for faster flash operations. Set to false for raw ROM communication.

---

MCP Integration Settings

Variable	Default	Description
MCP_ENABLE_PROGRESS	true	Enable MCP progress notifications for long-running operations.
MCP_ENABLE_ELICITATION	true	Enable MCP elicitation for interactive confirmation prompts (e.g., eFuse burns).
MCP_LOG_LEVEL	INFO	Logging level. Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL.

---

Performance Settings

Variable	Default	Description
ESP_MAX_CONCURRENT_OPERATIONS	5	Maximum number of parallel esptool subprocess operations. Must be between 1 and 20. Controls concurrency for batch programming and other parallelized operations.
ESP_OPERATION_TIMEOUT	300	Global timeout in seconds for individual esptool operations.

---

Development Settings

Variable	Default	Description
DEV_ENABLE_HOT_RELOAD	false	Enable hot reload for server code changes during development.
DEV_MOCK_HARDWARE	false	Enable hardware mocking for testing without physical devices.
DEV_ENABLE_TRACING	false	Enable detailed operation tracing for debugging.

---

Production Settings

Variable	Default	Description
PRODUCTION_MODE	false	Enable production mode. Affects logging verbosity and security defaults. Can also be enabled via the --production CLI flag.
PROD_ENABLE_SECURITY_AUDIT	true	Run security audits as part of production operations.
PROD_REQUIRE_CONFIRMATIONS	true	Require explicit confirmation for destructive operations in production mode.

---

QEMU Settings

Variable	Default	Description
QEMU_XTENSA_PATH	(auto-detect)	Path to qemu-system-xtensa binary from the Espressif QEMU fork. Auto-detected from ~/.espressif/tools/qemu-xtensa/*/qemu/bin/qemu-system-xtensa.
QEMU_RISCV_PATH	(auto-detect)	Path to qemu-system-riscv32 binary from the Espressif QEMU fork. Auto-detected from ~/.espressif/tools/qemu-riscv32/*/qemu/bin/qemu-system-riscv32.
QEMU_BASE_PORT	5555	Starting TCP port number for QEMU virtual serial connections. Instances are assigned sequential ports from this base.
QEMU_MAX_INSTANCES	4	Maximum number of concurrent QEMU instances. Each instance uses one TCP port from the pool.

Note

QEMU binary auto-detection uses glob patterns and selects the latest installed version (sorted alphabetically). If you have multiple QEMU versions installed, set the path explicitly to control which version is used.

---

Auto-Detection Behavior

ESP-IDF Path

When ESP_IDF_PATH is not set, the server checks these locations in order:

1. ~/esp/esp-idf
2. /opt/esp-idf
3. /usr/local/esp-idf

A directory is only accepted if it exists and contains idf.py at the root.

QEMU Binaries

When QEMU_XTENSA_PATH or QEMU_RISCV_PATH is not set, the server searches:

• Xtensa: ~/.espressif/tools/qemu-xtensa/*/qemu/bin/qemu-system-xtensa
• RISC-V: ~/.espressif/tools/qemu-riscv32/*/qemu/bin/qemu-system-riscv32

The latest matching version (by path sort order) is selected.

Project Roots

When MCP_PROJECT_ROOTS is not set, the server checks these directories and includes any that exist:

• ~/esp_projects
• ~/Arduino
• ~/Documents/Arduino
• /workspace/projects (Docker environments)

Additional roots are added at runtime when the MCP client provides workspace roots via the MCP roots protocol.

---

Validation

The server validates configuration at startup and raises an error if:

• esptool is not found at the configured path
• ESP_CONNECTION_TIMEOUT is outside the 5—300 second range
• ESP_MAX_CONCURRENT_OPERATIONS is outside the 1—20 range

An unusual (but valid) ESP_DEFAULT_BAUD_RATE value produces a warning but does not prevent startup.

---

Example Configuration

Minimal .env file for a development setup:

# Use a specific esptool version
ESPTOOL_PATH=/home/user/.local/bin/esptool

# Point to ESP-IDF
ESP_IDF_PATH=/home/user/esp/esp-idf

# Project directories
MCP_PROJECT_ROOTS=/home/user/esp_projects:/home/user/arduino_projects

# Enable debug logging
MCP_LOG_LEVEL=DEBUG

# Development features
DEV_ENABLE_HOT_RELOAD=true

Production .env file:

ESPTOOL_PATH=esptool
PRODUCTION_MODE=true
PROD_ENABLE_SECURITY_AUDIT=true
PROD_REQUIRE_CONFIRMATIONS=true
MCP_LOG_LEVEL=WARNING
ESP_MAX_CONCURRENT_OPERATIONS=10