Skip to content
mcesptool

Getting Started

This guide walks you through installing mcesptool, adding it to Claude Code, and verifying connectivity with an ESP device. The whole process takes about five minutes.

Prerequisites

Section titled “Prerequisites”
  • Python 3.10 or later — mcesptool uses modern type annotations and async features
  • esptool installed and available on your PATH (ships with ESP-IDF, or install standalone via pip install esptool)
  • An ESP32 or ESP8266 device connected over USB, or willingness to use QEMU emulation instead

Installation

Section titled “Installation”

  1. Install mcesptool

    The fastest way to run the server is with uvx, which downloads and runs the package in an isolated environment:

    Terminal window
    uvx mcesptool

    To add it as a project dependency instead:

    Terminal window
    uv add mcesptool

  2. Add to Claude Code

    Register mcesptool as an MCP server so Claude Code can invoke its tools:

    Terminal window
    claude mcp add mcesptool -- uvx mcesptool

  3. Verify esptool is available

    mcesptool shells out to esptool for all chip communication. Confirm it is installed:

    Terminal window
    which esptool.py && esptool.py version

  4. Connect your device

    Plug in your ESP board over USB. On Linux, the device typically appears at /dev/ttyUSB0 or /dev/ttyACM0. On macOS, look for /dev/cu.usbserial-* or /dev/cu.SLAB_USBtoUART.

    Terminal window
    ls /dev/ttyUSB* /dev/ttyACM* 2>/dev/null

    If the port exists but is not accessible, add yourself to the dialout group:

    Terminal window
    sudo usermod -aG dialout $USER

    Log out and back in for the group change to take effect.

  5. Detect your chip

    Use esp_detect_chip to confirm mcesptool can communicate with the device:

    # MCP tool invocation
    esp_detect_chip(port="/dev/ttyUSB0")

    A successful response looks like:

    {
      "success": true,
      "port": "/dev/ttyUSB0",
      "baud_rate": 115200,
      "connection_time_seconds": 0.84,
      "chip_info": {
        "chip_type": "ESP32-S3",
        "mac_address": "dc:da:0c:xx:xx:xx"
      }
    }

    For more detail, pass detailed=True to include flash size, crystal frequency, and feature flags:

    esp_detect_chip(port="/dev/ttyUSB0", detailed=True)

Troubleshooting

Section titled “Troubleshooting”

If esp_detect_chip fails:

  • “No ESP devices found” — check your USB cable. Some cables are charge-only and do not carry data.
  • Permission denied — on Linux, ensure your user is in the dialout group (see step 4 above).
  • Timeout — hold the BOOT button on your board while the tool connects, then release. Some boards require manual bootloader entry.

Run esp_scan_ports() to see all detected serial ports and their status.

Next steps

Section titled “Next steps”