Esp MCP

1[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/horw-esp-mcp-badge.png)](https://mseep.ai/app/horw-esp-mcp)
2 
3### Goal
4The goal of this MCP is to:
5- Consolidate ESP-IDF and related project commands in one place.
6- Simplify getting started using only LLM communication.
7 
8### How to contribute to the project
9 
10Simply find a command that is missing from this MCP and create a PR for it!
11 
12If you want someone to help you with this implementation, just open an issue.
13 
14 
15### Notice
16This project is currently a **Proof of Concept (PoC)** for an MCP server tailored for ESP-IDF workflows.
17 
18**Current Capabilities:**
19 
20**Core Features:**
21*   `run_esp_idf_install`: Install ESP-IDF dependencies and toolchain via `install.sh`.
22*   `create_esp_project`: Create a new ESP-IDF project.
23*   `setup_project_esp_target`: Set target chip for ESP-IDF projects (esp32, esp32c3, esp32s3, etc.).
24*   `build_esp_project`: Build ESP-IDF projects with incremental build support.
25*   `list_esp_serial_ports`: List available serial ports for ESP devices.
26*   `flash_esp_project`: Flash built firmware to connected ESP devices.
27*   `run_pytest`: Run pytest tests with pytest-embedded support for ESP-IDF projects.
28 
29**Additional Features:**
30*   Flexible ESP-IDF path management: supports per-project ESP-IDF versions via `idf_path` parameter.
31*   SDK config management: supports custom `sdkconfig_defaults` files for build configuration (multiple files can be specified separated by semicolons).
32*   Build time tracking for performance monitoring.
33*   Optional port specification for flashing operations.
34*   Includes experimental support for automatic issue fixing based on build logs.
35 
36**Vision & Future Work:**
37The 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.
38 
39We envision features such as:
40*   Broader ESP-IDF command support (e.g., `monitor`, `menuconfig` interaction if feasible).
41*   Device management and information retrieval.
42*   Integration with other embedded development tools and platforms.
43 
44Your ideas and contributions are welcome! Please feel free to discuss them by opening an issue.
45 
46 
47### Install
48 
49First, clone this MCP repository:
50 
51```bash
52git clone git@github.com:horw/esp-mcp.git
53```
54 
55Then, configure it in your chatbot.
56 
57The 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.
58 
59```json
60{
61    "mcpServers": {
62        "esp-run": { // "esp-run" is an arbitrary name you can assign to this server configuration.
63            "command": "<path_to_uv_or_python_executable>",
64            "args": [
65                "--directory",
66                "<path_to_cloned_esp-mcp_repository>", // e.g., /path/to/your/cloned/esp-mcp
67                "run",
68                "main.py" // If using python directly, this might be just "main.py" and `command` would be your python interpreter
69            ],
70            "env": {
71                "IDF_PATH": "<path_to_your_esp-idf_directory>" // e.g., ~/esp/esp-idf or C:\\Espressif\\frameworks\\esp-idf
72            }
73        }
74    }
75}
76```
77 
78A few notes on the configuration:
79 
80*   **`command`**: This should be the full path to your `uv` executable if you are using it, or your Python interpreter (e.g., `/usr/bin/python3` or `C:\\Python39\\python.exe`) if you plan to run `main.py` directly.
81*   **`args`**:
82    *   The first argument to `--directory` should be the absolute path to where you cloned the `esp-mcp` repository.
83    *   If you're using `uv`, the arguments `run main.py` are appropriate. If you're using Python directly, you might only need `main.py` in the `args` list, and ensure your `command` points to the Python executable.
84*   **`IDF_PATH`**: (Optional) This environment variable can 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](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html) for installation instructions. **Note**: All tools support an `idf_path` parameter that can be manually specified when calling the tool, allowing you to use different ESP-IDF versions for different projects without setting the environment variable. If `idf_path` is not provided, the tool will use the `IDF_PATH` environment variable if available.
85 
86### Usage
87 
88Once 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:
89 
90*   "Install ESP-IDF dependencies for the ESP-IDF installation at `/path/to/esp-idf`."
91*   "Set the target chip to esp32s3 for the project in `/path/to/my/esp-project`."
92*   "Build the project located at `/path/to/my/esp-project` using the `esp-mcp`."
93*   "Build the project with custom sdkconfig defaults: `sdkconfig.defaults;sdkconfig.ci.release`."
94*   "Run pytest tests for the project at `/path/to/my/esp-project` targeting esp32c3."
95*   "Flash the firmware to my connected ESP32 device for the project in `my_app`."
96 
97The MCP server will then execute the corresponding ESP-IDF commands (like `idf.py build`, `idf.py set-target`, `idf.py flash`, `pytest`) based on the tools implemented in `main.py`.
98 
99The `result.gif` below shows an example interaction:
100 
101![Result](./result.gif)
102 
103 
104### Examples
105 
106 
1071. Build and Flash
108<img src="./examples/build-flash.png">
109 
110### Star History
111 
112[![Star History Chart](https://api.star-history.com/svg?repos=horw/esp-mcp&type=Date)](https://star-history.com/#horw/esp-mcp&Date)
113 
114 
115 
116 
117 
118