crosspad-mcp-server

MCP (Model Context Protocol) server that gives Claude Code full control over the CrossPad development workflow — build, test, manage app packages, interact with the simulator, search code across repos. All from natural language.

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"
      }
    }
  }
}

Tools (28) + resources

v8 unifies platform-axis tools: build/run/kill/check/flash now take platform (or transport) as an arg instead of being split per-platform. Migration table 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

Tests

Simulator interaction

Git / repos

Code search & scaffolding

App package manager (crosspad-apps registry)

Resources

Migration: v7 → v8

Platform/transport now flows as an arg, not as part of the tool name. Net: 30 → 28 tools.

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-only; fullclean is IDF-only.

Migration: v6 → v7

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 (see above).

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              — 41 focused tool registrations (one tool per action)
  config.ts             — per-repo env vars, dynamic discovery, IDF/MSVC paths
  config.test.ts        — config unit tests (fs mocking)
  utils/
    exec.ts             — platform-aware command execution (MSVC/IDF/shell)
    git.ts              — repo status, submodule pins
    remote-client.ts    — TCP client for simulator (localhost:19840)
  tools/
    app-manager.ts      — crosspad_apps: multi-platform registry + Python subprocess
    architecture.ts     — interfaces, REGISTER_APP scan
    build.ts            — PC build + run
    build-check.ts      — build health check
    diff-core.ts        — submodule drift analysis
    idf-build.ts        — ESP-IDF build
    input.ts            — simulator input events
    log.ts              — exe log capture
    repos.ts            — multi-repo git status
    scaffold.ts         — app boilerplate generation
    screenshot.ts       — simulator screenshots
    settings.ts         — simulator settings R/W
    stats.ts            — simulator runtime stats
    symbols.ts          — cross-repo symbol search
    test.ts             — Catch2 test runner
    *.test.ts           — unit tests for each module

License

MIT — Part of the CrossPad project.