ESP-IDF Tools Local MCP Server: Build, Flash, and Manage Projects from Your AI Assistant

Espressif recently introduced the Documentation MCP server, a remote service that gives AI agents access to official Espressif documentation directly inside your editor. It helps with code generation, reviews, troubleshooting, and migration – all grounded in real, up-to-date docs.

But documentation lookup is only half the story. Once the AI knows what to do, it still cannot do it: setting the target, building the firmware, flashing it to a device, or checking the project state all remain manual steps.

The ESP-IDF Tools local MCP server closes that gap. It is a stdio-based MCP server built into idf.py that exposes project actions and state to any MCP-capable AI client. Instead of copying commands from a chat window into a terminal, you can tell the assistant to set the target to ESP32-C6, build the project, list connected devices, and flash – and it will execute each step directly.

Together, the two servers form a complete AI-assisted workflow: the Documentation server provides knowledge, and the Tools server provides actions.

Available Tools and Resources

#

The Tools MCP server exposes tools (actions the AI can execute) and resources (read-only project data).

Tools:

Resources:

The listed tools map directly to familiar idf.py subcommands, so the AI is effectively running the same operations you would run manually. The resources give the AI enough context to answer questions like “has this project been built?” or “which serial ports are available?” without requiring you to check yourself.

Preparing the Environment

#

Before you begin, make sure your environment meets the following requirements:

• Obtain the EIM installer v0.8.1 or newer
• Using EIM, install ESP-IDF v6.0 or newer
  • During ESP-IDF installation, enable the mcp feature – see EIM CLI Configuration - Global Features for how to enable specific features
• An MCP-capable AI client such as Cursor IDE or Claude Code

Starting the Server

#

The Tools MCP server is a local stdio server. MCP defines two transport types: HTTP-based servers run remotely and the AI client connects to them over the network, while stdio-based servers run as local processes on your machine and communicate with the AI client through standard input/output (stdin/stdout). The Tools MCP server uses the stdio transport – the AI client spawns it as a subprocess and exchanges messages with it directly, with no remote service or authentication involved.

There are two ways to start the server, depending on your environment:

Option 1: Using eim run (recommended)

eim run "idf.py mcp-server"

EIM spawns a new process with the ESP-IDF environment already activated. This is the best option for AI clients that do not inherit your shell environment, such as Cursor IDE.

Option 2: Using idf.py directly

idf.py mcp-server

Run this from a shell where the ESP-IDF environment is already activated (e.g., after running . ./export.sh). If you are not inside the project directory, point to it explicitly:

idf.py -C /path/to/your/project mcp-server

Note: In both cases, the server must be started from (or pointed at) a valid ESP-IDF project directory.

Setting Up the Tools MCP Server

#

Configuring the Tools MCP server follows the same pattern as any other MCP integration: register the server in your AI client, open your ESP-IDF project, and start using the assistant. The examples below cover Cursor IDE and Claude Code, but the same approach applies to any MCP-capable AI client – consult your client’s documentation on how to register a local stdio MCP server.

If you also use the Documentation MCP server, you can register both servers in the same configuration. For example, in Cursor’s .cursor/mcp.json:

{
  "mcpServers": {
    "esp-idf-eim": {
      "command": "eim",
      "args": [
        "run",
        "idf.py mcp-server"
      ],
      "env": {
        "IDF_MCP_WORKSPACE_FOLDER": "${workspaceFolder}"
      }
    },
    "espressif-docs": {
      "url": "https://mcp.espressif.com/docs"
    }
  }
}

Example Workflow

#

Here is a realistic multi-step session showing how the Tools MCP server works in practice:

Step 1 – Configure and build

Set the target to esp32c6 and build the project.

The assistant calls set_target("esp32c6") followed by build_project(). Build progress and the final result (success or error output) are reported back.

Step 2 – Check devices and flash

Show me connected devices and flash the firmware.

The assistant reads project://devices to discover available serial ports, then calls flash_project(port) with the appropriate port.

Step 3 – Verify the result

What is the current build status?

The assistant reads project://status and project://config to report the target chip, IDF version, project path, and which build artifacts are present.

Step 4 – Clean up

Clean the build artifacts.

The assistant calls clean_project() to remove the build directory contents.

Each of these steps runs through a controlled interface that reflects the actual state of your project. The assistant does not guess or simulate – it executes real idf.py commands and returns real output.

Using Both MCP Servers Together

#

The Documentation and Tools MCP servers are designed to complement each other. The Documentation server gives the AI access to datasheets, API references, migration guides, and hardware design guidelines. The Tools server lets it act on that knowledge by building, flashing, and managing your project.

When both servers are configured, the AI can handle end-to-end tasks that span documentation lookup and project actions. For example:

Check the ESP-IDF documentation for the recommended I2C pins on ESP32-C3,
update the pin configuration in my project, and build it.

In this scenario, the assistant queries the Documentation MCP server for the hardware reference, updates the source code, then uses the Tools MCP server to build the project and verify the result.

For setup instructions for the Documentation MCP server, see the companion article.

Troubleshooting

#

“MCP dependencies not available”

The mcp feature is not installed in your ESP-IDF environment. Re-run the EIM installer and make sure to enable the mcp feature. See the EIM documentation for details.

“Open the MCP server in a valid ESP-IDF project directory”

The server could not find a valid ESP-IDF project. Make sure you are either running the server from inside a project directory, or that IDF_MCP_WORKSPACE_FOLDER points to one. A valid project directory contains a CMakeLists.txt that includes the ESP-IDF project CMake file.

Server not appearing in Cursor

Verify that eim is on your system PATH by running eim --version in a terminal. If Cursor cannot find eim, the server will fail to start silently. Also confirm the .cursor/mcp.json file exists and contains valid JSON.

Conclusion

#

The ESP-IDF Tools local MCP server gives AI assistants a direct, structured way to interact with your ESP-IDF projects. The core benefit is straightforward: the assistant can execute real project actions – set target, build, flash, clean, and query status – not just describe them.

Combined with the Documentation MCP server, it forms a complete AI-assisted development loop: look up the right API or configuration, apply changes to the code, build, and flash – all from a single conversation.

If you already use an MCP-capable AI client, this feature is an easy way to make AI assistance more practical in everyday ESP-IDF work. Start by adding the MCP server to your AI client configuration, connect it to your project, and use natural language to drive the familiar set_target -> build -> flash workflow.