Picocalc MCP

PicoCalc MicroPython

A MicroPython firmware and script collection for the Clockwork Pi PicoCalc handheld device, powered by the Raspberry Pi Pico 2W. Features:

• 320x320 LCD display with flicker-free rendering
• Membrane keyboard with VT100 terminal
• Categorized, arrow-key navigable app menu (auto-hides libraries)
• Games (Tetris, Snake), 4-instrument Synthesizer, Strudel live-coding music, WiFi Manager, local LLM client (Ollama)
• SSH client with ECDH-SHA2-NISTP256, AES-128-CTR encryption, interactive VT100 terminal
• Development dashboard with file manager, editor, diff, REPL, eject
• SD card script auto-discovery

---

Quick Start

• YouTube PicoCalc 2.0 Demo: https://youtu.be/gf3ittEwFJ8

1. Flash the Firmware

1. Power off the PicoCalc and unplug USB.
2. Hold BOOTSEL on the Pico 2W, then connect USB.
3. A drive named RP2350 appears.
4. Copy MicroPython/firmware/picocalc_micropython_pico2w.uf2 to that drive.
5. The device reboots automatically.

2. Deploy Files to the Device

Option A: Dashboard (Recommended)

The easiest way -- a local web UI that handles everything:

python3 MicroPython/tools/dashboard.py

This opens a browser dashboard where you can:

• Deploy All -- pushes boot files, modules, and scripts in one click
• Browse device files, view diffs, push individual files
• Drag-and-drop .py files to upload
• Side-by-side diff -- click a modified file to see device vs local changes color-coded
• New script -- create scripts from a starter template with one click
• REPL -- run Python on the device from the browser (30s timeout per command)
• Eject -- safely disconnect with on-device countdown, then unplug USB

First run will prompt to install mpremote if needed. Requires Python 3.7+.

Adding new files: Scripts in modules/ and sd/py_scripts/ are auto-discovered by the dashboard. Root-level files (like boot.py) must be added to FILE_MAP in dashboard.py to appear.

Option B: AI-Assisted Development (Vibe Coding)

Let your AI coding assistant talk directly to the PicoCalc -- write code, push it, test on device, iterate, all from the AI conversation.

MCP Server (Recommended)

MCP gives AI tools native access to the device with no dashboard running. Install from PyPI:

pip install picocalc-mcp

Then add to your .mcp.json or Claude Desktop config:

{

"mcpServers": { "picocalc": { "command": "picocalc-mcp" } } }

Or run directly from the repo: "args": ["/path/to/PicoCalc/mcp/mcp_server.py"]

Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible tool. Full setup guide: [MCP_README.md](mcp/MCP_README.md)

See it in action: MCP & Dashboard Demo

Claude Code Skills (Optional)

For Claude Code users, the code-skills repo provides PicoCalc-specific skills that teach the AI how to write correct apps, use the hardware APIs, review code, and handle device operations. The MCP server gives the AI hands to interact with the device; the skills give it the knowledge to build for it.

# With skill-deployer installed, just paste a URL:

"install this skill https://github.com/LofiFren/code-skills/tree/main/skills/picocalc-app"

Dashboard REST API (Legacy)

If you already have the dashboard running, AI tools can also use its HTTP endpoints:

curl -s http://localhost:8265/api/device                          # Device status

curl -s -X POST http://localhost:8265/api/exec -H 'Content-Type: application/json' \ -d '{"code": "print(1+1)"}' # Run Python on device curl -s -X POST http://localhost:8265/api/push -H 'Content-Type: application/json' \ -d '{"file": "sd/py_scripts/my_app.py"}' # Push file to device curl -s "http://localhost:8265/api/diff?file=sd/py_scripts/synth.py" # Diff local vs device curl -s -X POST http://localhost:8265/api/eject # Safe disconnect

All endpoints: /api/device, /api/exec, /api/push, /api/pull, /api/files, /api/diff, /api/local/tree, /api/eject, /api/reset, /api/cleanup

Option C: Manual

Use Thonny, mpremote, or rshell to copy files to the Pico's internal flash.

Copy these to the Pico root (`/`):

MicroPython/boot.py       --> /boot.py

MicroPython/main.py --> /main.py MicroPython/modules/ --> /modules/ (entire directory)

Copy SD card scripts:

MicroPython/sd/py_scripts/*.py  --> SD card /py_scripts/

Do NOT copy these to the device (they run on your computer, not the PicoCalc):

tools/             <-- Dashboard web UI (runs on your computer)

picocalcdisplay/ <-- C source, compiled into firmware vtterminal/ <-- C source, compiled into firmware firmware/ <-- UF2 images and Dockerfile

3. Prepare the SD Card

1. Format an SD card as FAT32 (4GB-32GB recommended).
2. Create a py_scripts folder on the SD card.
3. Copy all .py files from MicroPython/sd/py_scripts/ into that folder.
4. Insert the SD card into the PicoCalc.

Or use the Dashboard -- click Deploy Scripts to push all scripts to the SD card over USB.

4. Boot

Power cycle the PicoCalc. The boot splash shows initialization progress, then the main menu appears with arrow-key navigation.

---

Repository Structure

MicroPython/

|-- boot.py --> Copy to device / |-- main.py --> Copy to device / (launches menu) |-- boot_thonny.py --> Deploy as /boot.py for Thonny users |-- boot_dev.py --> Deploy as /boot.py for dev mode (REPL only) |-- cleanup.py --> (Optional) one-time cleanup, or use dashboard Cleanup button |-- modules/ --> Copy to device /modules/ | |-- picocalc.py Hardware abstraction (display + keyboard) | |-- vt.py VT100 terminal emulator | |-- py_run.py Categorized app menu (auto-hides libraries) | |-- enhanced_sd.py SD card initialization | |-- picocalc_system.py System utilities | |-- sdcard.py SD card driver | |-- checksd.py SD card verification | |-- pye.py Built-in text editor | |-- colorer.py Terminal color support | |-- default_style.py Syntax highlighting styles | |-- highlighter.py Code syntax highlighting | |-- flush.py Module cache flushing | \-- mkdir.py Directory creation utility |-- sd/py_scripts/ --> Copy contents to SD card /py_scripts/ | |-- tetris.py Tetris with sound effects | |-- snake.py Snake with high scores | |-- synth.py 4-instrument synthesizer with piano keyboard | |-- strudel.py Strudel mini-notation parser + sequencer (library) | |-- strudel_live.py Live-coding music UI (color themes, playhead) | |-- strudel_demo.py Interactive tutorial: learn the mini-notation | |-- ProxiScan.py BLE proximity scanner & fox hunt tool | |-- WiFiManager.py WiFi scanning & connection manager | |-- picocalc_ollama.py Local LLM client (Ollama) | |-- brad.py WiFi utility library | |-- demo.py Visual display showcase (grayscale, animation) | \-- editor.py On-device file browser + code editor |-- sd/samples/ --> Copy to SD card /samples/ (Strudel drum kit) | \-- bd/sd/hh/cp.raw 8-bit PCM one-shots for the picosampler engine |-- firmware/ Prebuilt UF2 firmware images | |-- picocalc_micropython_pico2w.uf2 (v1.25.0, stable) | |-- picocalc_v127_pico2w.uf2 (v1.27.0, patched) | |-- picocalc_v128_pico2w.uf2 (v1.28.0, native USB + audio engine) | |-- Dockerfile Build for v1.25.0 | |-- Dockerfile.v127 Build for v1.27.0 + USB fix | |-- Dockerfile.v128 Build for v1.28.0 (no USB patch) | \-- USB_REGRESSION_FIX.md RP2350 USB bug report |-- micropython.cmake Top-level build config for C modules |-- picocalcdisplay/ C display driver (compiled into firmware) | |-- picocalcdisplay.c | |-- picocalcdisplay.h | |-- font6x8e500.h | \-- micropython.cmake |-- vtterminal/ C terminal emulator (compiled into firmware) | |-- vtterminal.c | |-- vtterminal.h | |-- font6x8.h | \-- micropython.cmake |-- picosampler/ C audio engine (DMA-PWM sampler, compiled in) | |-- picosampler.c 8-voice 8-bit PCM mixer, stereo PWM out | |-- micropython.cmake | |-- make_samples.sh wav -> 8-bit PCM converter (ffmpeg) | \-- generate_drums.py synthesize a starter drum kit (no deps) |-- tools/ Development tools | |-- dashboard.py Web UI server (run this!) | |-- bottle.py Vendored web framework (zero install) | \-- static/ | |-- index.html Dashboard frontend | \-- vendor/ CodeMirror editor (vendored, offline) mcp/ MCP server for AI assistants |-- mcp_server.py MCP server (pip install picocalc-mcp or run directly) \-- MCP_README.md Full setup guide

---

Applications

| Editor | On-device file browser and code editor -