crosspad-mcp-server

MCP (Model Context Protocol) server that gives an LLM full control over the CrossPad development workflow — build, flash and test firmware (ESP32-S3 + STM32), drive the PC simulator, trace live variables over SWD, route audio on the physical device, manage app packages, and search code across every repo of the ecosystem. All from natural language.

30 tools · 4 resources · 2 bundled Claude Code skills · stdio & HTTP transports

Install

claude mcp add crosspad -- npx -y crosspad-mcp-server

Or with custom repo paths:

claude mcp add crosspad \
  --env CROSSPAD_IDF_ROOT=/path/to/platform-idf \
  --env CROSSPAD_PC_ROOT=/path/to/crosspad-pc \
  -- npx -y crosspad-mcp-server

That's it. Restart Claude Code and the tools are available.

Alternative: .mcp.json in your project

Add to your repo root — Claude Code picks it up automatically:

{
  "mcpServers": {
    "crosspad": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "crosspad-mcp-server"],
      "env": {
        "CROSSPAD_IDF_ROOT": "/path/to/platform-idf",
        "CROSSPAD_PC_ROOT": "/path/to/crosspad-pc"
      }
    }
  }
}

Alternative: Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "crosspad": {
      "command": "npx",
      "args": ["-y", "crosspad-mcp-server"],
      "env": {
        "CROSSPAD_IDF_ROOT": "/path/to/platform-idf"
      }
    }
  }
}

Related MCP server: devctl-mcp

Skills (start here)

This package ships two Claude Code skills (bundled in the crosspad plugin):

• crosspad — the entry point. An ecosystem map, install/config guide, per-role guides (user / firmware dev / server contributor), a tool cheat-sheet, and an FAQ. A fresh agent should read this first. Lives at skills/crosspad/SKILL.md; run bash skills/crosspad/scripts/doctor.sh to check your environment. Reference guides bundled with it:

  • reference/philosophy.md — the CrossPad design principles ("write once, run everywhere", thin platform repos) and where code belongs

  • reference/hil-testing.md — hardware-in-the-loop testing on the real device: the flash→smoke workflow, every tools/hil_*.py script, the CDC/SysEx remote control surface, and the hardware traps that cost real debugging sessions

  • reference/repos.md, reference/tools.md, reference/install.md, reference/faq.md, per-role guides

• swd-tracer — real-time SWD variable tracing for CrossPad r20 (STM32G0B1) over ST-Link (see the SWD tracing section below).

Install both as a plugin:

/plugin marketplace add CrossPad/crosspad-mcp     # or a local path to this repo
/plugin install crosspad@crosspad

Tools (30) + resources

v8 unified platform-axis tools: build/run/kill/check/flash take platform (or transport) as an arg instead of being split per-platform. Migration tables at the bottom of this file.

Each tool is focused on a single action. Strict schema validation (ranges on MIDI/pad values, enums on platforms/repos) catches bad inputs before execution.

Build & flash

SWD tracing (crosspad_trace)

Non-halting real-time trace of STM32G0B1 firmware variables via ST-Link — the same technique as ST-Studio/CubeMonitor but driven directly from the LLM session.

Recommended: the swd-tracer skill. This repo ships a Claude Code skill (skills/swd-tracer/) + plugin manifest so a fresh agent automatically understands the tracer and can walk you through configuring every environment (pyOCD venv, config paths, udev rules, the Debug ELF) and the doctor→symbols→start→read→ui→stop workflow. Install it as a plugin:

/plugin marketplace add CrossPad/crosspad-mcp     # or a local path to this repo
/plugin install crosspad@crosspad

The plugin bundles BOTH this MCP server and the skill, so a new machine gets the tracer end-to-end in one install. (Already running the server? The skill alone also lives at skills/swd-tracer/SKILL.md.)

Prerequisites (the skill's scripts/setup-venv.sh automates this)

Install pyocd and pyelftools into a Python venv (system Python is usually PEP-668 locked, so a venv is required):

bash skills/swd-tracer/scripts/setup-venv.sh
# or manually:
python3 -m venv ~/.local/share/crosspad-mcp/venv
~/.local/share/crosspad-mcp/venv/bin/pip install "pyocd>=0.44" pyelftools

Point the server at that venv via config_set (or set it directly in ~/.config/crosspad-mcp/config.json):

action=config_set  key=pyocd_python  value=~/.local/share/crosspad-mcp/venv/bin/python
action=config_set  key=stm_elf_path  value=/path/to/CrossPad_STM32_r20.elf

Linux udev note: without a udev rule the ST-Link probe requires root. Run bash skills/swd-tracer/scripts/install-udev-rules.sh (writes /etc/udev/rules.d/49-stlink.rules, then replug the probe), or add the official rules from pyocd / ST so your user can open the device without sudo.

Actions

Signal names accept array indexing, struct members, and whole-array/slice expansion: s_inputs[0], s_adc_raw[3], hpcd.Init.speed, s_adc_raw[*], s_inputs[0:8] (out-of-bounds indices are rejected against the DWARF length).

Example — trace ADC rail and pad inputs

action=doctor
# resolve any blocking issues...
action=symbols  query=s_vbat
action=start    signals=["s_vbat_mv","s_inputs[0]"]  rate_hz=100
action=status
action=read     max_points=500
action=save
action=stop

Tests

Simulator interaction

Git / repos

Code search & scaffolding

App package manager (crosspad-apps registry)

Resources

Migrations

Run/kill/check are PC-only today (the platform arg is reserved for future symmetry — IDF firmware doesn't run on the host). Build modes are validated per-platform: reconfigure is PC/STM-only; fullclean is IDF-only.

Tools removed (logic moved to docs): crosspad_scaffold_app, crosspad_test_scaffold. Tools consolidated:

Net: 42 tools → 30 tools + 1 resource (v7). Subsequent unification in v8 → 28 tools; v9 added crosspad_trace and crosspad_audio_route → 30.

All tools return a uniform envelope: { "success": boolean, ...data, "error"?: string }. On failure the result also has the MCP-protocol isError: true flag set so clients can route errors distinctly from successful calls.

Each tool carries MCP annotations (readOnlyHint, destructiveHint, openWorldHint) — clients use these for confirmation prompts. Read-only tools (status, search, list) skip the prompt; destructive tools (commit, flash, build_idf clean, apps_install) trigger one.

Configuration

Each repo path is individually configurable via env vars. If not set, falls back to $CROSSPAD_GIT_DIR/<repo-name> (flat layout).

Repos are discovered dynamically — only repos that exist on disk appear in tool results. No flat directory structure is assumed when env vars are set.

Transport

stdio (default) — npx crosspad-mcp-server. Standard MCP transport for Claude Code / Claude Desktop / IDE plugins.

HTTP (--http <port>) — npx crosspad-mcp-server --http 3000. Exposes a Streamable HTTP endpoint at http://localhost:<port>/mcp for remote dev boxes or browser-based MCP clients. Stateful sessions (Mcp-Session-Id header echoed after initialize). One transport, multi-session multiplexed internally.

# Minimal HTTP smoke test:
npx crosspad-mcp-server --http 3000
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"x","version":"0"}}}'

How it works

Static tools (build, repos, code, apps) work without the simulator — they operate on the filesystem, git, and Python package manager.

Interactive tools (sim) communicate with the running PC simulator via TCP on localhost:19840 using newline-delimited JSON.

Streaming — long-running tools (build, test, log) emit output line-by-line via MCP logging, so Claude sees progress in real-time.

App manager — reads registry JSON directly for listing (aggregated across all repos). Mutations delegate to app_manager.py (at tools/ for IDF, scripts/ for PC/Arduino) from crosspad-apps.

Development

git clone https://github.com/CrossPad/crosspad-mcp.git
cd crosspad-mcp
npm install
npm run dev      # watch mode
npm run build    # one-shot build
npm test         # run unit tests
npm run test:watch  # tests in watch mode

src/
  index.ts              — 30 focused tool registrations (one tool per action) + resources
  config.ts             — per-repo env vars, dynamic discovery, IDF/MSVC/STM paths
  utils/                — platform-aware exec (MSVC/IDF/shell), git helpers,
                          TCP client for the simulator (localhost:19840)
  tools/
    build.ts / idf-build.ts / stm-build.ts   — per-platform builds behind crosspad_build
    idf-flash.ts / stm-flash.ts              — ESP (uart/ota) and STM (swd/dfu) flashing
    build-check.ts / diff-core.ts / repos.ts — health checks, submodule drift, git status
    trace-*.ts            — SWD tracer: session, symbols (DWARF), buffer, export,
                            device-state, write, doctor, web UI
    audio-route.ts        — runtime codec routing over MIDI SysEx
    input.ts / midi.ts / screenshot.ts / settings.ts / stats.ts — simulator interaction
    app-manager.ts        — multi-platform app registry + Python subprocess
    architecture.ts / symbols.ts             — interfaces, REGISTER_APP scan, symbol search
    test.ts               — Catch2 test runner
    *.test.ts             — unit tests alongside each module
skills/                 — bundled Claude Code skills (crosspad, swd-tracer)
tracer/                 — SWD tracer runtime (pyOCD host script + protocol docs)
vscode-extension/       — companion VS Code extension

License

MIT — Part of the CrossPad project.