micropython

micropython-claude-plugin

A plugin to interact with micropython devices within Claude

Features

• File sync
  • upload
  • download
  • newest-wins
• Pull an image from the device
• Push an image to the device
• Run the device program
  • stream output to Claude
  • let Claude send commands

Architecture

• Python-based
• MCP server
• USB-Serial I/O

Installation

Claude Code (recommended)

Install the plugin from the marketplace — no manual setup. On first use, the plugin's launcher (bin/launch.py) creates an isolated venv under ${CLAUDE_PLUGIN_DATA}/venv, installs itself into it, and starts the MCP server. Plugin updates are detected by content hash and re-installed automatically on the next MCP server start.

The only host requirement is python (3.10+) on PATH.

Claude Desktop / other MCP hosts

Install the package into a Python environment and point your MCP host at the console script:

pip install -e .

{
  "mcpServers": {
    "micropython": {
      "command": "micropython-claude",
      "args": []
    }
  }
}

mpremote

The plugin's venv ships mpremote for ad-hoc command-line use. Invoke it through the bundled shim — bootstrap is shared with the MCP server so the venv is auto-created on first call:

python "${CLAUDE_PLUGIN_ROOT}/bin/mpremote.py" connect COM4 ls :

Or call the venv binary directly: ${CLAUDE_PLUGIN_DATA}/venv/Scripts/mpremote.exe (Windows) / ${CLAUDE_PLUGIN_DATA}/venv/bin/mpremote (POSIX).

Usage

Running the MCP Server manually

# Start the server (connects to device when requested via tools)
micropython-claude

# Or auto-connect to a specific port on startup
micropython-claude --port /dev/ttyUSB0 --baudrate 115200

Development

For contributors hacking on the server itself, install editable and run the console script directly — bypassing the launcher:

pip install -e .
micropython-claude

Available Tools

Connection Tools

Tool	Description
list_devices	List available serial ports that might be MicroPython devices
connect	Connect to a MicroPython device on a serial port
disconnect	Disconnect from the current device
device_info	Get information about the connected device

File Operations

Tool	Description
list_files	List files and directories on the device
read_file	Read a file from the device
write_file	Write content to a file on the device
delete_file	Delete a file from the device
mkdir	Create a directory on the device
upload_file	Upload a file from local filesystem to the device
download_file	Download a file from the device to local filesystem
sync_file	Sync a file between local and device (upload/download/newest-wins)
sync_directory	Sync a directory between local and device

Image Operations

Tool	Description
pull_image	Pull a filesystem image from the device (backup)
push_image	Push a filesystem image to the device (restore)
compare_image	Compare device filesystem with a saved image

Execution Tools

Tool	Description
execute	Execute Python code on the device
run_file	Run a Python file on the device
run_main	Run the main.py file on the device
send_command	Send a command to the device REPL
interrupt	Send interrupt (Ctrl+C) to stop running program
soft_reset	Perform a soft reset of the device
get_variable	Get the value of a variable on the device
set_variable	Set a variable on the device

Examples

Basic Workflow

1. List available devices to find your MicroPython board
2. Connect to the device
3. List files to see what's on the device
4. Upload/download files as needed
5. Execute code or run programs
6. Disconnect when done

File Sync Example

The sync_file tool supports three modes:

• upload: Always copy from local to device
• download: Always copy from device to local
• newest: Compare modification times and sync the newest version

Creating Backups

Use pull_image to create a complete backup of your device filesystem:

• Creates a compressed tar archive
• Includes all files and directories
• Stores device metadata

Restore with push_image to restore from a backup.

Supported Devices

Works with any MicroPython device accessible via USB serial, including:

• Raspberry Pi Pico / Pico W
• ESP32 / ESP8266
• STM32 boards
• Other MicroPython-compatible boards

Requirements

• Python 3.10+
• pyserial
• mcp (Model Context Protocol SDK)
• click