Overview

The ESP MCP Server is a Model Context Protocol (MCP) server that exposes common ESP-IDF workflows to language models and agent systems. It wraps typical ESP-IDF tasks — installation, project creation, target selection, build, flash and test — behind a small set of tools so an LLM can orchestrate firmware development and deployment through a single endpoint. This is useful for automating repetitive tasks in development, CI, or when building conversational developer assistants that need to operate on ESP projects.

Designed as a proof-of-concept, the server focuses on pragmatic coverage of the most frequently used commands while leaving room to add more capabilities (monitoring, menuconfig interaction, device inventory, etc.). It supports per-project ESP-IDF versions, custom sdkconfig defaults, optional flashing ports, and basic build-time telemetry; these options help teams keep reproducible builds and integrate the server into different environments.

Features

Install ESP-IDF toolchain and dependencies (via install script).
Create new ESP-IDF projects from templates.
Set ESP chip target (esp32, esp32s3, esp32c3, etc.) for a project.
Build projects with incremental builds and optional sdkconfig defaults.
List available serial ports for connected devices.
Flash built firmware to connected ESP devices (optional port override).
Run pytest (pytest-embedded) for hardware / simulated tests.
Support for per-project idf_path and env var fallback (IDF_PATH).
Experimental: build-time tracking and automated issue-fixing hints based on build logs.

Installation / Configuration

Clone the repository and run the MCP server using a Python interpreter or uv (if used by your agent runtime).

Clone the repo:

git clone [email protected]:horw/esp-mcp.git
cd esp-mcp

Start the MCP server (example using Python):

# Start with Python
python3 main.py

Example MCP server configuration (JSON snippet you can adapt to your chatbot/agent system):

{
  "mcpServers": {
    "esp-run": {
      "command": "/usr/bin/python3",
      "args": [
        "--directory",
        "/path/to/cloned/esp-mcp",
        "main.py"
      ],
      "env": {
        "IDF_PATH": "/home/user/esp/esp-idf"
      }
    }
  }
}

Notes:

command may point to a uv binary instead of python depending on your runtime.
IDF_PATH is optional. Tools accept an idf_path parameter to override the environment variable on a per-call basis.
sdkconfig_defaults supports multiple files separated by semicolons (e.g., sdkconfig.defaults;sdkconfig.ci).

Available Tools

The MCP exposes a concise set of tools (functions) representing ESP-IDF activities. Below is a quick reference.

Tool name	Purpose
run_esp_idf_install	Run ESP-IDF install script to fetch dependencies and toolchain
create_esp_project	Initialize a new ESP-IDF project
setup_project_esp_target	Set the ESP target chip for a project
build_esp_project	Build the project (supports incremental builds & sdkconfig defaults)
list_esp_serial_ports	Enumerate serial ports available on the host
flash_esp_project	Flash firmware to a connected device (optional port param)
run_pytest	Execute pytest tests (pytest-embedded support)

Each tool accepts parameters like project path, idf_path, target, sdkconfig_defaults, and optional flashing port.

Use Cases

Build and flash a local project

LLM prompt: “Build /home/dev/my_app and flash the connected ESP32.”
What happens: toolchain is used to build (incrementally), the server lists serial ports, then flashes the built firmware. You can optionally pass a port.

Use a different ESP-IDF version per project

Scenario: CI needs a specific ESP-IDF revision. Call build_esp_project with idf_path=/opt/esp/esp-idf-v4.4.3 so the server builds with that framework without changing system-wide env.

CI reproducible builds with custom sdkconfig

Example: Build using sdkconfig.defaults;ci/sdkconfig.ci so multiple default files are merged for a release build.

Hardware-in-the-loop tests

LLM prompt: “Run pytest for path /home/ci/tests targeting esp32c3.” The server runs pytest with pytest-embedded integration against the target hardware.

Automated troubleshooting (experimental)

If a build fails, the server can optionally produce analysis/hints or attempt fixes based on the build log. This is a PoC feature — treat suggestions as guidance rather than guaranteed fixes.

Tips & Best Practices

Prefer passing idf_path per-request in multi-version environments to avoid global env changes.
Use sdkconfig_defaults to keep reproducible build flags for CI and local builds.
When flashing multiple devices, specify the port to avoid ambiguity.
The server is a PoC: treat it as a developer convenience and verify production flashing steps manually before automating mass deployments.

For the latest source, examples, and issue tracker see the project repository: https://github.com/horw/esp-mcp. Contributions (new tools, bug fixes, improved error handling) are welcome via pull requests.

ESP MCP Server for IDF Build and Flash