ESP-IDF MCP server

The ESP-IDF MCP server provides a simplified interface for working with ESP-IDF projects through large language model interactions. It allows you to execute common ESP-IDF commands like building and flashing firmware without having to remember the exact syntax, making embedded development more accessible.

Installation

To get started with the ESP-IDF MCP server, follow these steps:

Clone the Repository

First, clone the MCP repository to your local machine:

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

Configure the MCP Server

After cloning, you need to configure the server in your chatbot system. Below is a sample configuration:

{
    "mcpServers": {
        "esp-run": {
            "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>"
            }
        }
    }
}

Configuration Details

• command: The full path to your uv executable or Python interpreter
• args:
  • Set --directory to the absolute path where you cloned the repository
  • Use run main.py for uv or just main.py if using Python directly
• IDF_PATH: Must point to your ESP-IDF installation directory
  • If you haven't installed ESP-IDF yet, follow the official documentation

Usage

Once configured, you can interact with the ESP-IDF MCP server through your chatbot using natural language. Here are some examples of what you can do:

Building Projects

To build an ESP-IDF project:

Build the project located at /path/to/my/esp-project

This executes the equivalent of idf.py build in the specified directory.

Cleaning Build Files

To clean project build files:

Clean the build files for the ESP32 project in examples/hello_world

This runs the equivalent of idf.py fullclean in the specified directory.

Flashing Firmware

To flash built firmware to a connected ESP device:

Flash the firmware to my connected ESP32 device for the project in my_app

You can also specify a port if needed:

Flash the firmware to my ESP32 connected on COM3

Automatic Issue Fixing

The server includes experimental support for automatically fixing issues based on build logs. If your build fails, you can ask the chatbot to analyze the error and suggest fixes.

Current Capabilities

The ESP-IDF MCP server currently supports:

• Basic ESP-IDF project build commands
• Flashing firmware to connected ESP devices
• Specifying ports for device connections
• Experimental automatic issue fixing based on build logs

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "esp-run" '{"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>"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "esp-run": {
            "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>"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "esp-run": {
            "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>"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect