crosspad-mcp
Talk to your CrossPad. Let Claude do the toolchain.
crosspad-mcp is an MCP server that teaches Claude Code (or any MCP client) how to develop for the CrossPad pad controller. You say "flash the new build and check that it boots"; it runs the ESP-IDF build, asks you to confirm the flash, opens the console, runs the smoke scenario and tells you what happened — with the hardware traps already built in, so you don't have to remember which serial port reboots the board when you open it.
What you can do with it
Every card is a real prompt. The tools named underneath are what runs — you never have to call them yourself.
| Say this… | …and this happens |
|---|---|
| "Build the firmware and flash it over OTA." | crosspad_build platform=idf streams the build, crosspad_flash transport=ota asks for confirmation, then streams the upload. New app directories are detected and the fullclean is done for you. |
| "Show me what's on the simulator screen." | crosspad_run launches the PC sim, crosspad_screenshot returns the LCD as an image Claude can actually look at. Then "press pad 5", "turn the encoder left twice" — crosspad_input. |
| "Play a drum pattern on the pads and record what comes out." | crosspad_stimulus hits the pads with real timings, crosspad_capture records the board through its own USB-audio endpoint, crosspad_analyze gives a verdict (onsets, clicks, silence, velocity curve). |
| "Why did it crash?" | crosspad_diagnose_crash — reset reason, registers, backtrace decoded against the ELF that is actually flashed, heap after restart. One call. |
| "Watch the battery charger state machine while I plug the cable in." | crosspad_trace polls STM32 variables live over ST-Link without halting the core, and plots them. |
| "Install the sampler app and rebuild." | crosspad_apps_install app_name=sampler adds the submodule from the crosspad-apps registry, then a clean build. |
"Where is IPadLogicHandler implemented?" | crosspad_interface_implementations across every repo of the ecosystem, or crosspad_symbol for clangd-precise definitions and call hierarchies. |
| "Is my board even connected?" | crosspad_devices and crosspad_doctor — which USB mode it is in, which ports belong to it, what is missing on the host, and how to fix each thing. |
Quick start
claude mcp add crosspad -- npx -y crosspad-mcp-server
Restart Claude Code, then ask:
is my CrossPad connected, and is the toolchain set up?
That runs crosspad_doctor. Every failed check comes with a fix. The server
assumes your repos live side by side under ~/GIT/ — if they don't,
set the paths once.
Installing the bundled crosspad skill gives Claude the ecosystem map, the
per-role guides and the hardware traps up front:
/plugin marketplace add CrossPad/crosspad-mcp
/plugin install crosspad@crosspad
How it is organised
Only the core toolset is visible when the server starts, so the tool list
stays small. Claude enables the others as the conversation needs them — or you
start the server with --toolsets device,sim.
flowchart LR
core["core · always on<br/>devices · doctor · snapshot<br/>build · flash · repo status · tasks<br/>bench lease"]
sim["sim<br/>PC simulator: run, screenshot,<br/>input, MIDI, settings, tests"]
device["device<br/>the board over USB: console,<br/>CDC verbs, UI driving, USB mode"]
hil["hil<br/>scenarios, pad stimulus,<br/>audio capture + analysis, BLE"]
code["code<br/>symbols, interfaces,<br/>docs search"]
git["git<br/>submodule drift,<br/>update, commit"]
apps["apps<br/>crosspad-apps registry"]
trace["trace<br/>SWD live variables"]
core --> sim & device & code & git & apps
device --> hil
core --> trace
Anything that writes to a device or your host is tiered. Flashing, DFU and
SWD writes come back as confirmation required first; --read-only removes
every writing tool from the list entirely. Long operations (builds, flashes,
scenarios) run as tasks you can check on, wait for or cancel.
Who is it for
- You build and drive CrossPad firmware — mostly the simulator, sometimes the board. Start with the user guide.
- You work on the firmware itself — flash, console, HIL scenarios, crash diagnosis, SWD. Read the firmware developer guide and HIL testing.
- You want to extend this server — the contributor guide and the Development section.
Going deeper
- Usage reference — every install path, every tool and toolset, resources and prompts, configuration, HTTP transport, the v10 migration table.
- FAQ — the questions that cost people an afternoon.
- CHANGELOG
License
GPL-3.0-or-later — see LICENSE. Part of the CrossPad project. Releases up to 10.3.0 were published under MIT.