ESP-IDF FastMCP Server

You can manage ESP-IDF related tooling through an MCP server that exposes commands to query ESP-IDF versions, list targets and serial ports, select a serial port, and build or clean projects. This centralized server lets you drive ESP-IDF workflows from any MCP client over HTTP or via a local process.

How to use

After the server is running, connect an MCP client to the HTTP endpoint at http://127.0.0.1:8080/mcp and invoke the registered tools to manage ESP-IDF tasks. You can also run the local, Python-based server configuration to expose the same MCP interface as a standalone process. Use the tools to view supported ESP targets, inspect serial ports, select a port, compile projects, clean builds, and set the target device.

How to install

Prerequisites you need to install before running the ESP-IDF MCP server:

• Python 3.8 or higher
• FastMCP library (for MCP server tooling)
• ESP-IDF toolchain (for ESP-IDF related tooling)

Install the required Python dependencies using the following command. This installs the project’s runtime requirements including the MCP server bindings.

pip install -r requirements.txt

Run the server directly or with a configuration file

You have two ways to start the server. Choose the one that best fits your workflow.

python app.py

This starts an HTTP server listening on 127.0.0.1:8080 and exposes the MCP endpoints.

Alternatively, use a declarative MCP configuration to run the server. This approach defines the server behavior in a JSON file and executes it with the fastmcp runner.

fastmcp run fastmcp.json

Configuration examples

Below are two MCP server connection configurations that reflect how this server can be exposed either over HTTP or as a local process. Use only the form that matches how you run the server.

{
  "mcpServers": {
    "esp_idf_http": {
      "type": "http",
      "url": "http://127.0.0.1:8080",
      "args": []
    }
  }
}

Additional notes

If you prefer running the MCP server as a local process, ensure you use the exact runtime command shown. For example, when using Python to start the server locally, the command is python app.py and its working directory should contain the app.py script.

You can also register the local process as an MCP server entry with an explicit command and arguments, so you can manage it from a central MCP client just like the HTTP version.

Available tools

get_esp_idf_version

Fetches the current ESP-IDF version information available from the ESP-IDF installation or environment.

list_esp_targets

Lists supported ESP targets/chips that ESP-IDF can target for building.

list_serial_ports

Lists serial ports on the host that contain a valid description, using pyserial to filter out ports without a meaningful description.

select_serial_port

Selects the target serial port to be used by subsequent ESP-IDF operations.

get_selected_serial_port

Retrieves the currently selected serial port.

compile_project

Compiles the ESP-IDF project and returns both stdout and stderr for inspection.

clean_project

Cleans the ESP-IDF project build artifacts.

set_target

Sets the ESP-IDF build target device for subsequent operations.