mpftp

MicroPython and CircuitPython board tools for VS Code and compatible derivatives

mpftp brings microcontroller board management directly into your modern code editor (VS Code, Google Antigravity IDE, Cursor, VSCodium):

• An In-Editor Alternative to Thonny: Edit board files, transfer files, install packages (mip / circup), and flash firmware without switching back and forth to external IDEs or standalone tools.
• Embedded Serial REPL: The interactive REPL opens directly inside your editor's Terminal panel, allowing you to test and inspect code live alongside your editor tabs and AI coding agents.
• Wi-Fi Fast MIP Transfers: Transferring wifi.py and creating secrets.py on Wi-Fi enabled boards enables on-board mip package installation directly over the network, which is significantly faster than serial file transfers.
• Visual Firmware Builder: A GUI companion for firmware workspaces (such as cmods), allowing you to download official releases or build and flash custom firmware from the UI.
• Completely Optional: If you are already comfortable with command-line tools (mpremote, esptool, circup) or standalone IDEs, you can continue using them. mpftp is provided as an all-in-one in-editor workbench.
• No Editor Required: pip install -i https://test.pypi.org/simple/ pydevices-mpftp && python -m mpftp opens a local installable PWA — file transfer and REPL in a browser tab, no VS Code needed. (In the published 0.0.3 package the PWA is not yet included — run from a clone until the next release.)

Published as pydevices.mpftp under PyDevices.

Documentation

• User guide — getting started, File Transfer, REPL, Firmware workspace, autosize, troubleshooting
• Aggregator & user modules — workspace micropython.cmake / manifest-micropython.py contract
• Developers guide — architecture, discovery contract, packaging, contribution
• Agent guide — agent/CLI workflows: board ops, flash recovery, pointers to aggregator docs
• Integrations — MCP server (25 typed board tools) plus a Claude Code plugin and a Codex CLI config snippet

Features

• Dual-Pane File Transfer: Local ↔ board file management (upload, download, mkdir, new file, delete, rename, drag-and-drop)
• Live In-Editor Editing: Open and edit files directly on the board with automatic save-back and optional SHA-256 verification
• Integrated Terminal REPL: Hardware serial REPL embedded right in the editor Terminal workspace
• Automatic Interpreter Detection: Connects over serial, automatically identifies MicroPython or CircuitPython, and synchronizes the RTC
• Package Installation: Install packages with mip (MicroPython) or circup (CircuitPython)
• Visual Firmware Workbench: Detect board hardware, download official MicroPython builds, or build and flash custom firmware workspaces (ESP32, RP2040, SAMD)
• AI Agent-Friendly: Local TCP RPC and agent CLI interface sharing the active editor session, plus an MCP server for Claude Code / Codex

Requirements

• VS Code or compatible derivative (such as Google Antigravity IDE, Cursor, VSCodium) (engine ^1.85.0)
• Python 3 with mpremote
  • WSL / Windows serial: Windows Python + pip install mpremote
  • Native Linux: venv or mpftp.pythonPath
• For CircuitPython packages: circup on the same Python (pip install circup)

Install

Not yet on the VS Code Marketplace or Open VSX. Download the .vsix from the latest GitHub release and install it: Extensions: Install from VSIX… → mpftp-*.vsix.

Or build the .vsix from source:

cd extension && npm install && npm run package
# Extensions: Install from VSIX… → mpftp-*.vsix

Development (Cursor Remote-WSL):

./scripts/install-cursor-wsl.sh   # runs npm install/compile in extension/ itself
# Developer: Reload Window

Quick start

1. mpftp: Connect to Board — pick a port
2. Open File Transfer — move files; open REPL for the shell
3. Install Package — mip (MicroPython) or circup (CircuitPython) by detected interpreter
4. Firmware — Detect a board, then Download an official MicroPython image or Build from a firmware workspace

A firmware workspace is a folder that contains micropython/ (or is the MicroPython tree). Port SDKs go in that workspace as directories/symlinks, or via environment variables — see the user guide.

Commands (selection)

Command	Action
mpftp: Connect to Board	Port picker; interrupt + interpreter-aware clean
mpftp: Resume Last Device	Reconnect previous port
mpftp: Open File Transfer in Panel / Editor	Dual-pane UI
mpftp: Open REPL	ANSI terminal
mpftp: Build & Flash Firmware…	MicroPython firmware panel
mpftp: Interrupt / Soft Reset / Hard Reset	Board control
mpftp: Install Package	mip or circup by interpreter

Settings (selection)

Setting	Purpose
mpftp.workspacePath	Firmware workspace (MicroPython + optional SDK trees)
mpftp.pythonPath	Sidecar Python (empty on WSL → Windows python.exe)
mpftp.buildPythonPath	Native Python for builds
mpftp.verifyTransfers	SHA-256 after file transfer
mpftp.compileOnUpload	Compile .py to .mpy via mpy-cross on upload (MicroPython only)
mpftp.autoReconnectAfterReset	Reconnect after hard reset

Full list: VS Code Settings → search mpftp, or user guide.

Status and support

Development Status: Alpha (per pyproject.toml classifiers). Boards are driven over serial for both MicroPython and CircuitPython — the two behave differently enough that it's worth reading the MicroPython vs. CircuitPython boundary before relying on parity between them. Issues: github.com/PyDevices/mpftp/issues.

License

MIT — see LICENSE.