home / mcp / esp mcp server

ESP MCP Server

Provides an ESP-IDF focused MCP server to build and flash ESP projects via an LLM-powered workflow.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "horw-esp-mcp": {
      "command": "<path_to_uv_or_python_executable>",
      "args": [
        "--directory",
        "<path_to_cloned_esp-mcp_repository>",
        "run",
        "main.py"
      ],
      "env": {
        "IDF_PATH": "<path_to_your_esp-idf_directory>"
      }
    }
  }
}

This MCP server streamlines ESP-IDF workflows by letting you manage ESP-IDF project commands through conversational prompts. It consolidates build and flash actions in a single interface so you can begin, monitor, and adjust ESP-IDF projects using text-based instructions.

How to use

You interact with the ESP-MCP server through your MCP client to perform common ESP-IDF tasks. You can request builds, clean builds, and flashing of firmware to connected devices. You can also rely on the server to adapt commands based on your project path and device connection, making ESP-IDF workflows smoother when using an LLM-powered assistant.

Typical usage patterns include asking to build a specific ESP-IDF project, cleaning build artifacts, and flashing the resulting firmware to a connected device. The server is designed to execute the ESP-IDF commands appropriate to your request, such as building a project, cleaning build files, or flashing firmware, using the configured runtime environment.

How to install

Prerequisites you need before installing this MCP server are Git, a supported runtime (Python or uv), and ESP-IDF installed on your machine.

Step by step commands you should run:

# 1) Clone the MCP server repository
git clone [email protected]:horw/esp-mcp.git

# 2) Install and run the MCP server via your preferred runtime
# Example using Python (adjust to your environment):
python3 main.py

# If you prefer uv (Node-based or UVX workflow), ensure uv is installed and run the server accordingly
# The JSON config snippet shows how to wire the MCP server into a chatbot or agent system
```} ,{

Configuration details

Configure the MCP server within your MCP client so the client can communicate with ESP-MCP. The following JSON demonstrates a stdio-based setup where the server runs via your Python or uv runtime and points to the ESP-MCP repository files.

{
  "mcpServers": {
    "esp_mcp": {
      "command": "<path_to_uv_or_python_executable>",
      "args": [
        "--directory",
        "<path_to_cloned_esp-mcp_repository>",
        "run",
        "main.py"
      ],
      "env": {
        "IDF_PATH": "<path_to_your_esp-idf_directory>"
      }
    }
  }
}
```"}]} ,{

Available tools

build

Assemble the ESP-IDF project into a firmware image by invoking the ESP-IDF build process.

fullclean

Remove all build artifacts and start a clean build from scratch.

flash

Flash the built firmware to a connected ESP device, with optional port specification.