esp-mcp is a proof-of-concept (PoC) project for an MCP (Model Context Protocol) server targeting ESP-IDF workflows. Its goal is to centrally manage ESP-IDF and related project commands and simplify onboarding so that it can be used solely through LLM communication.
Main capabilities:
- run_esp_idf_install: Install ESP-IDF dependencies and toolchain via install.sh.
- create_esp_project: Create a new ESP-IDF project.
- setup_project_esp_target: Set the target chip for an ESP-IDF project (such as esp32, esp32c3, esp32s3, etc.).
- build_esp_project: Build an ESP-IDF project, with support for incremental builds.
- list_esp_serial_ports: List the serial ports available for ESP devices.
- flash_esp_project: Flash the built firmware to a connected ESP device.
- run_pytest: Run pytest tests supporting pytest-embedded for an ESP-IDF project.
Additional features:
- Flexible ESP-IDF path management: Support different ESP-IDF versions per project via the idf_path parameter.
- SDK configuration management: Support custom sdkconfig_defaults files for build configuration (multiple files can be specified, separated by semicolons).
- Build time tracking for performance monitoring.
- Optional port specification for flash operations.
- Includes experimental support for automatic issue fixing based on build logs.
Usage: First clone the MCP repository, then configure it in the chatbot. In the example configuration JSON snippet, command should be the full path to the uv executable, or the Python interpreter path used when running main.py directly (such as /usr/bin/python3 or C:\Python39\python.exe). The first argument of --directory in args should be the absolute path to the cloned esp-mcp repository; if using uv, the arguments are run main.py; if using Python directly, args may only need main.py, and make sure command points to the Python executable. IDF_PATH is an optional environment variable and can point to the root directory of the ESP-IDF installation. All tools support the idf_path parameter, which can be specified manually at call time, so that different ESP-IDF versions can be used for different projects without setting environment variables; if idf_path is not provided, the tools will use the available IDF_PATH environment variable.
After configuring and running the esp-mcp server, the LLM or chatbot can interact through the tools defined in this MCP. For example, you can ask the chatbot to: install dependencies for the ESP-IDF installation located at /path/to/esp-idf; set the target chip to esp32s3 for the project in /path/to/my/esp-project; build the project located at /path/to/my/esp-project using esp-mcp; build the project using the custom sdkconfig defaults sdkconfig.defaults;sdkconfig.ci.release; run pytest tests targeting esp32c3 for the project in /path/to/my/esp-project; flash the firmware to a connected ESP32 device for the project in my_app. The MCP server will execute the corresponding ESP-IDF commands (such as idf.py build, idf.py set-target, idf.py flash, pytest) according to the tools implemented in main.py.
Applicable scenarios: Suitable for scenarios involving embedded development using ESP32 series chips and ESP-IDF, especially for developers who want to drive workflows such as build, flash, and test in natural language through an LLM or chatbot.
Limitations: This project is currently a proof of concept (PoC). The long-term vision is to expand it into a comprehensive toolkit for interacting with embedded devices, possibly integrating the home assistant platform, and simplifying access to documentation for ESP-IDF and related technologies. Envisioned future features include broader ESP-IDF command support (such as monitor and menuconfig interaction, if feasible), device management and information retrieval, and integration with other embedded development tools and platforms. Ideas and contributions are welcome through issue discussions.
