This MCP server focuses on ESP-IDF workflows and centralizes common ESP32 project commands into a single interface. With esp-run, you can install ESP-IDF dependencies, create projects, configure targets, build, flash, and run tests using natural prompts. Tools include run_esp_idf_install to set up the ESP-IDF toolchain, create_esp_project to scaffold new projects, setup_project_esp_target to select the target ESP chip (e.g., esp32, esp32s3, esp32c3), build_esp_project for incremental builds, list_esp_serial_ports to detect connected devices, flash_esp_project to flash firmware, and run_pytest to execute tests with pytest-embedded support. The MCP also supports per-project IDF path management through idf_path, and SDK config handling via sdkconfig_defaults, enabling multiple defaults separated by semicolons. You can interact with these tools via simple prompts like “Install ESP-IDF dependencies for the ESP-IDF installation at /path/to/esp-idf” or “Build the project at /path/to/esp-project using esp-mcp.” The goal is to streamline ESP-IDF workflows through LLM-driven commands without leaving the chat context.

Prerequisites:

• Python 3.8+ installed on your system
• ESP-IDF installed or accessible via IDF_PATH or idf_path parameter
• A cloning environment with git

Installation steps:

1. Clone the MCP repository: git clone git@github.com:horw/esp-mcp.git

2. Open the folder and prepare the environment for MCP usage. Ensure you know where ESP-IDF is installed (IDF_PATH) if you plan to use environment-wide configuration:

   • If you use a chatbot integration, configure the MCP endpoint with the esp-run server name and the appropriate command/args as shown in the mcp_config example.

3. Install required runtime (choose one path for running the MCP commands):

   • If using uv (preferred for MCPs that rely on an interpreter-based runner):
     • Ensure Python 3 is installed
     • Install uv (or the uvx variant if you prefer): pip install uv

       or if you use uvx for Python embedding: pip install uvx

   • If using a direct Python invocation: ensure Python is available and main.py is executable via the configured command.

4. Configure your chatbot or agent with the ESP MCP server details (see mcp_config example). Include the path to the cloned esp-mcp repo and the IDF_PATH as needed by your ESP-IDF setup.

5. Verify connectivity by running a lightweight command, e.g. to list available ESP serial ports once the server is configured.

Note: The ESP-IDF installation and project workflows rely on the IDF_PATH environment variable or the idf_path parameter in the tool calls. If you do not set IDF_PATH globally, you can provide it per-call via the env or idf_path in your MCP invocation.

Tips and common considerations:

• IDF_PATH handling: You can specify IDF_PATH via the environment variable or per-command using idf_path in your tool calls. This enables using multiple ESP-IDF versions across projects.
• sdkconfig_defaults: You can pass multiple defaults separated by semicolons (e.g., sdkconfig.defaults;sdkconfig.ci.release) to customize builds.
• Target setup: Use setup_project_esp_target to select targets like esp32, esp32s3, esp32c3, etc., prior to building.
• Flashing: The flash_esp_project tool supports optional port specification; specify the serial port if multiple devices are connected.
• Automated issue fixing: There is experimental support for automatic issue fixing based on build logs; use it when you encounter recurrent build errors.
• Build times: The MCP includes build time tracking to help you optimize workflows.
• Per-project ESP-IDF versions: You can manage per-project ESP-IDF versions with idf_path, reducing cross-project contamination.
• If you encounter permission or driver issues with serial ports, ensure your user has access to the USB-Serial device or run with appropriate privileges.