The goal of this MCP is to:

• Consolidate ESP-IDF and related project commands in one place.
• Simplify getting started using only LLM communication.

Simply find a command that is missing from this MCP and create a PR for it!

If you want someone to help you with this implementation, just open an issue.

This project is currently a Proof of Concept (PoC) for an MCP server tailored for ESP-IDF workflows.

Current Capabilities:

• Supports basic ESP-IDF project build commands.
• Flash built firmware to connected ESP devices with optional port specification.
• Includes experimental support for automatic issue fixing based on build logs.

Vision & Future Work: The long-term vision is to expand this MCP into a comprehensive toolkit for interacting with embedded devices, potentially integrating with home assistant platforms, and streamlining documentation access for ESP-IDF and related technologies.

We envision features such as:

• Broader ESP-IDF command support (e.g., monitor, menuconfig interaction if feasible).
• Device management and information retrieval.
• Integration with other embedded development tools and platforms.

Your ideas and contributions are welcome! Please feel free to discuss them by opening an issue.

This project requires Python 3.11+ and uses uv for dependency management.

1. Install uv (if not already installed):

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone and setup:

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

3. Test run:

   uv run python main.py

That's it! uv sync automatically handles Python version installation and dependency management.

First, complete the Environment Setup above to prepare your development environment.

Then, configure the MCP server in your chatbot.

The JSON snippet below is an example of how you might configure this esp-mcp server within a chatbot or an agent system that supports the Model Context Protocol (MCP). The exact configuration steps and format may vary depending on the specific chatbot system you are using. Refer to your chatbot's documentation for details on how to integrate MCP servers.

{
    "mcpServers": {
        "esp-run": { // "esp-run" is an arbitrary name you can assign to this server configuration.
            "command": "uv",
            "args": [
                "--directory",
                "<path_to_cloned_esp-mcp_repository>", // e.g., /path/to/your/cloned/esp-mcp
                "run",
                "python",
                "main.py"
            ],
            "env": {
                "IDF_PATH": "<path_to_your_esp-idf_directory>" // e.g., ~/esp/esp-idf or C:\\Espressif\\frameworks\\esp-idf
            }
        }
    }
}

A few notes on the configuration:

• command: Use uv as the command since we're using uv for dependency management.
• args:
  • --directory should be the absolute path to where you cloned the esp-mcp repository.
  • run python main.py tells uv to run the main.py file using the project's virtual environment.
• IDF_PATH: This environment variable must point to the root directory of your ESP-IDF installation. ESP-IDF is Espressif's official IoT Development Framework. If you haven't installed it, please refer to the official ESP-IDF documentation for installation instructions.

Once the esp-mcp server is configured and running, your LLM or chatbot can interact with it using the tools defined in this MCP. For example, you could ask your chatbot to:

• "Build the project located at /path/to/my/esp-project using the esp-mcp."
• "Clean the build files for the ESP32 project in the examples/hello_world directory."
• "Flash the firmware to my connected ESP32 device for the project in my_app."

The MCP server will then execute the corresponding ESP-IDF commands (like idf.py build, idf.py fullclean, idf.py flash) based on the tools implemented in main.py.

The result.gif below shows an example interaction:

1. Build and Flash