How to add ESP-MCP to Windsurf

Centralize ESP-IDF/ESP32 commands and drive embedded builds, flashing, and tests via LLM-driven MCP tools. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 151★ · stdio · no auth

Windsurf config for ESP-MCP

git clone git@github.com:horw/esp-mcp.git

{
  "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>"
      }
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the ESP-MCP config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5ESP-MCP's tools become available to Cascade.

Before you start

ESP-IDF (Espressif IoT Development Framework) installed; IDF_PATH can point to its root directory or be passed per-tool via idf_path
uv or a Python interpreter to run main.py
git to clone the repository
A connected ESP device for flashing operations

What ESP-MCP can do in Windsurf

run_esp_idf_install

Install ESP-IDF dependencies and toolchain via install.sh.

create_esp_project

Create a new ESP-IDF project.

setup_project_esp_target

Set the target chip for ESP-IDF projects (esp32, esp32c3, esp32s3, etc.).

build_esp_project

Build ESP-IDF projects with incremental build support; supports custom sdkconfig_defaults files (multiple separated by semicolons) and build time tracking.

list_esp_serial_ports

List available serial ports for ESP devices.

flash_esp_project

Flash built firmware to connected ESP devices, with optional port specification.

run_pytest

Run pytest tests with pytest-embedded support for ESP-IDF projects.

Security

No license file is declared in the repository. The server executes ESP-IDF toolchain commands (install.sh, idf.py build/set-target/flash) and pytest locally, and can flash firmware to connected hardware, so it requires local toolchain access and connected devices. It is explicitly described as a Proof of Concept.

ESP-MCP + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the ESP-MCP config there under the "mcpServers" key and restart the client.

Is ESP-MCP safe to use with Windsurf?

Is this an official Espressif project?

No. It is a community Proof-of-Concept MCP server (repository horw/esp-mcp), not an official Espressif release.

How do I point the server at my ESP-IDF installation?

Set the IDF_PATH environment variable in the MCP server config to your ESP-IDF root directory. Alternatively, every tool accepts an idf_path parameter so you can use different ESP-IDF versions per project; if idf_path is omitted, the tool falls back to IDF_PATH if available.

Is there a published package to install?

No. You clone the repository and run main.py via uv or Python directly, then register it as a stdio MCP server in your client's mcpServers configuration.

View repo Full ESP-MCP page