# ESP-IDF MCP

> ESP-IDF MCP is an open-source MCP server for developer tools. Build, flash, monitor and test ESP-IDF firmware on real ESP32 boards from an agent. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, Windows, Linux, macOS
- **Repository:** https://github.com/maty403/esp-idf-mcp
- **MCP Registry name:** io.github.Maty403/esp-idf-mcp
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools), [manufacturing](https://ai-powered.com/categories/manufacturing)
- **Listing updated:** 2026-11-18

## About

This community-built local server closes the loop for embedded work: an agent can compile an ESP-IDF project, flash a connected board over serial, capture the boot log and run pytest-embedded hardware tests, rather than only writing firmware code. Builds go through idf.py, so sdkconfig behaves as usual, and the ESP-IDF install is found automatically.

Its serial monitor is session based. monitor_open, monitor_read, monitor_send and monitor_close give a persistent session read for new lines only, with idle sessions releasing the port after 30 seconds by default, reconnection after USB re-enumeration, ANSI stripping, collapsing of repeated lines and folding of boot output before the app starts. Flashing opens a monitor automatically on the chosen port, and read_chip_info reports the chip model, revision, crystal, MAC and flash details.

The README compares it with Espressif's built-in Tools MCP server, noting that it adds component management, bundled examples, device sessions and hardware tests. The quick start targets Windows with Codex, and a board is only needed for flashing, monitoring and tests.

## Features

- **Build and flash:** Compiles with idf.py and flashes via esptool in one workflow.
- **Persistent serial monitor:** Sessions that return only new log lines, with a full-log escape hatch.
- **Chip info:** Reads model, revision, crystal, MAC and flash size from the board.
- **Hardware-in-the-loop tests:** Runs pytest-embedded suites against the real device.
- **Component management:** Add or remove component dependencies and browse bundled examples.
- **Agent-friendly logs:** Strips colours, collapses repeats and reports folded line counts.

## Good for

- Have an agent build and flash a firmware change then summarise the boot log
- Run hardware tests after each code edit
- Identify the chip and flash size of an unknown board
- Debug a crash by polling the serial monitor
- Scaffold a project from a bundled ESP-IDF example

## Install

### Claude Code (Terminal)

```sh
claude mcp add esp-idf-mcp -- uvx esp-idf-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "esp-idf-mcp": {
      "command": "uvx",
      "args": [
        "esp-idf-mcp"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "esp-idf-mcp": {
      "command": "uvx",
      "args": [
        "esp-idf-mcp"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "esp-idf-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "esp-idf-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "esp-idf-mcp": {
      "command": "uvx",
      "args": [
        "esp-idf-mcp"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "esp-idf-mcp": {
      "command": "uvx",
      "args": [
        "esp-idf-mcp"
      ]
    }
  }
}
```

## Tools

- `build_project`: Builds the project with idf.py
- `flash_project`: Flashes the board and opens a monitor session
- `read_chip_info`: Reports chip model, revision, crystal, MAC and flash details
- `monitor_open`: Opens a persistent serial monitor session
- `monitor_read`: Reads new lines from a monitor session
- `monitor_send`: Sends data to a monitor session
- `monitor_close`: Closes a monitor session

## FAQ

### What do I need installed?

ESP-IDF and Python 3.9 or newer; a board only for flashing, monitoring and hardware tests.

### How is it installed?

The README shows pip install and adding it to Codex with codex mcp add esp-idf -- esp-idf-mcp.

### Will it disturb other boards?

No, only the target port's monitor session is closed before flashing.

### How does it differ from Espressif's built-in MCP?

The README says it adds persistent monitor sessions, chip details, component management, bundled examples and pytest-embedded tests.

### Is ESP-IDF MCP free?

Yes. ESP-IDF MCP is open source, so you can use and self-host it for free.

### How do I add ESP-IDF MCP to Claude Code?

Run this command in your terminal: claude mcp add esp-idf-mcp -- uvx esp-idf-mcp

### What are the best alternatives to ESP-IDF MCP?

The closest alternatives to ESP-IDF MCP are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.

## Where this comes from

- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/esp-idf-mcp
