jumperless-mcp

A Model Context Protocol server for the Jumperless V5 breadboard computer by Architeuthis Flux. Drive the breadboard programmatically — connections, measurements, GPIO, signal generation, OLED, probe, overlay pixels — either from an LLM (Claude Desktop, Cursor, etc.) or directly from your terminal.

What is this?

A persistent USB-serial bridge that wraps the Jumperless V5's on-device MicroPython API as MCP tools. Plug in your V5, run the server, and either:

• AI mode: connect an MCP-aware AI tool (Claude Desktop, Cursor, Continue, custom bots, etc.) — the AI gets 42 typed tools for circuit-building, measurement, signal generation, and visual feedback.
• CLI mode: run subcommands directly to install the resident library, probe firmware, dump device files, etc. — no AI required.

Why does it exist?

"The biggest hurdle [the Jumperless-skill] runs into is finding the serial port and connecting to it... every time I clear the context it just blows tokens trying to figure out how to talk to it. I feel like a stripped down version of the app that connects to the REPL port would be super clutch." — Architeuthis Flux

This server is that stripped-down version. The MCP client launches the server once; the server holds the USB port across the entire session; the AI never has to re-discover the device or relearn the Raw REPL protocol.

Install

Three install paths — pick whichever matches you.

Option 1: Pre-built binary (no Rust toolchain needed)

Easiest if you just want to use the server. Download the archive for your platform from the latest release. Archive names follow the pattern jumperless-mcp-<version>-<platform>-<arch>.<ext>:

| Platform | Archive | Notes | |---|---|---| | Windows (Intel/AMD) | *-windows-x86_64.zip | Works on Windows 10 and later | | macOS (Apple Silicon) | *-macos-arm64.tar.gz | M1/M2/M3/M4; for Intel Macs use Option 2 or 3 | | Linux (x86_64) | *-linux-x86_64.tar.gz | Tested on Ubuntu 22.04+; should work on any glibc 2.34+ distro |

Windows:

1. Extract the .zip (right-click → Extract All).
2. Move jumperless-mcp.exe somewhere on your PATH — e.g. create C:\Users\<you>\bin\ and add it via Settings → System → About → Advanced system settings → Environment Variables.
3. First run shows a SmartScreen warning ("Windows protected your PC") because the binary isn't code-signed. Click More info → Run anyway. (OSS projects rarely sign Windows binaries — Microsoft's EV certs cost $200–400/yr.)

macOS (Apple Silicon):

tar xzf jumperless-mcp-*-macos-arm64.tar.gz
xattr -d com.apple.quarantine jumperless-mcp   # remove Gatekeeper quarantine
chmod +x jumperless-mcp
mv jumperless-mcp ~/.local/bin/                # or /usr/local/bin/ for system-wide

If you skip the xattr step macOS will say "cannot be opened because the developer cannot be verified." Alternative: right-click the binary in Finder → Open → Open in the confirmation dialog (one-time).

Linux (x86_64):

tar xzf jumperless-mcp-*-linux-x86_64.tar.gz
chmod +x jumperless-mcp
mv jumperless-mcp ~/.local/bin/                # ensure ~/.local/bin is on PATH

Verify (all platforms):

jumperless-mcp --version
jumperless-mcp --help

Option 2: Via cargo (needs Rust toolchain)

If you already have Rust installed (or want to install it from rustup.rs):

cargo install jumperless-mcp

Downloads source from crates.io, compiles, and installs the binary to ~/.cargo/bin/ (already on your PATH if you installed Rust via rustup). Verify with jumperless-mcp --version.

Option 3: Build from source

For local development or to pick up unreleased changes from main:

git clone https://github.com/LesbianVelociraptor/jumperless-mcp.git
cd jumperless-mcp
cargo install --path .

Platform notes (first-run, all install methods)

• Linux: you may need to be in the dialout group to access USB serial. Run sudo usermod -aG dialout $USER and log out / back in.
• macOS: no extra setup beyond Gatekeeper steps above.
• Windows: the V5 USB driver should auto-install on first plug-in. If COM-port enumeration fails, check Device Manager → Ports.

Use with an AI tool (Claude Code, Claude Desktop, or other MCP clients)

Plug in the Jumperless V5. Add the server to your MCP client config. Both of Anthropic's first-party tools (Claude Code CLI and Claude Desktop) are supported, as are third-party MCP clients like Cursor, Continue, and OpenCode.

Claude Code (terminal-based CLI)

The fastest path is the claude mcp add command, run once from any directory:

claude mcp add jumperless jumperless-mcp

Or edit ~/.claude.json (user-level) or .mcp.json (project-level) directly:

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

Open a new Claude Code session (claude in your terminal). The Jumperless tools should appear when you ask Claude to list its tools.

Claude Desktop (GUI app)

Edit claude_desktop_config.json. Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

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

Restart Claude Desktop. The Jumperless tools should appear in the tool list when you start a new chat.

Cursor / Continue / OpenCode / other MCP clients

Most MCP-aware tools take the same shape: a command and its args. The command is jumperless-mcp (no args needed for default server mode). Consult your specific client's MCP-config docs.

What the AI gets

On connect, the AI sees a tool list and can call any of the 42 tools below. There's an opening "ceremony" — a NASA-orange MCP CONNECTED marquee scrolls across the breadboard, and corner brackets light up as a persistent "MCP active" indicator. On disconnect, a reverse ceremony fires and the brackets clear. Both ceremonies are visual confirmation that the server is talking to the hardware; they can be skipped with --skip-ceremony for headless/CI runs.

Use directly via CLI (no AI required)

The same binary doubles as a normal command-line tool. Useful for installing the resident library, diagnosing firmware, dumping files, or just poking at the device without spinning up an AI client.

Help

jumperless-mcp --help                  # top-level help
jumperless-mcp firmware-probe --help   # subcommand help
jumperless-mcp library --help          # library subcommand group
jumperless-mcp library install --help  # nested subcommand help

Firmware diagnostic

jumperless-mcp firmware-probe             # human-readable output
jumperless-mcp firmware-probe --json      # structured JSON
jumperless-mcp firmware-probe --no-ceremony  # skip visual greeting

Reports the firmware codebase in use, API surface fingerprint, and installed resident-library version. Read-only — no device state is modified.

Resident library management

jumperless-mcp library install              # idempotent install
jumperless-mcp library install --force      # force reinstall
jumperless-mcp library uninstall            # remove /jumperless_mcp/
jumperless-mcp library check-installation   # report version + file presence
jumperless-mcp library verify               # size + hash check vs embedded source
jumperless-mcp library dump /jumperless_mcp/effects.py  # hexdump a device file

--json on any of these emits machine-readable output suitable for scripts.

Common options (apply to every subcommand)

--port COMx                # explicit serial port (auto-detected by default)
--log-level debug|info|warn|error
--skip-handshake           # debug: skip Raw REPL handshake
--skip-ceremony            # skip the connect/disconnect visual ceremony

Server lifecycle (manual operation)

Starting

Normally the MCP client launches the server as a subprocess — you don't start it by hand. The client invokes the command from your config, pipes JSON-RPC over stdio, and that's the server's input/output.

If you want to start it manually (e.g., for debugging or piping JSON-RPC yourself):

jumperless-mcp
# server is now reading JSON-RPC requests from stdin, writing responses to stdout.
# you can paste raw JSON-RPC if you really want, but practically: use an MCP client.

Stopping

The server exits cleanly when stdin closes (i.e. when the parent process / MCP client shuts it down). You can also Ctrl+C in the terminal. Either way, the disconnect ceremony fires before the process exits — corner brackets unpaint, OLED clears, USB port releases.

Things to know while it's running

• The USB port is exclusive. Only one process can hold it at a time. If the server is running for Claude Desktop and you try jumperless-mcp firmware-probe in another terminal, the second call will fail with a port contention error. Stop the MCP client first (or use a second physical device).
• Source edits require a restart. This is a compiled Rust binary, not a hot-reload script. After cargo install --path ., restart your MCP client to pick up the new binary.
• Library version is checked on connect. If you edit python/ files and run cargo install --path ., the resident library on the device is updated automatically when the next MCP session connects. No manual install step needed.
• Ceremony adds ~5-6s to first connect. If you don't want the visual flair (e.g. in a CI run or quick scripting), pass --skip-ceremony.

Tools exposed

The server exposes 42 MCP tools grouped by domain:

| Family | Tools | |---|---| | State | get_state (single-call snapshot of the entire board — circuit, rails, GPIO, ADC, overlays, plus an ASCII "pretty view" of the breadboard if you pass view: "pretty"), set_state | | Connections | connect, disconnect, nodes_clear, is_connected | | Slots | slot_save, slot_load, slot_discard, slot_has_changes, slot_get_current | | Voltage / Measurement | dac_set, dac_get, adc_get, adc_get_stats (multi-sample mean / min / max / stddev) | | Current sensing | ina_get_current, ina_get_voltage, ina_get_power | | Digital I/O | gpio_set, gpio_get, gpio_set_dir | | Waveform generator | wavegen_set_{output,wave,freq,amplitude,offset}, wavegen_start, wavegen_stop | | User interaction | oled_print, oled_clear, probe_read_blocking, probe_read_nonblocking, probe_button | | Graphic overlays | overlay_serialize, overlay_list, overlay_clear, overlay_clear_all | | Core / Context / Debug | core_pause, core_resume, context_get, context_toggle, dev_exec_python (typed escape hatch) |

The API tracks the Jumperless LLM tools specification maintained by Architeuthis Flux. Some firmware-side quirks (e.g., get_state() throwing UnicodeError on V5 firmware 5.6.6.2) are worked around inside this server — see docs/TROUBLESHOOTING.md and the source comments for the firmware-contract notes uncovered during build.

About

Author: Samantha Edward (@LesbianVelociraptor)

Built collaboratively with Anthropic Claude. Architecture and design decisions are mine; many implementation passes, review iterations, and the bundler tooling went through Claude. Full development history is in the commit log.

This is my first open-source release. The Jumperless V5 was a kindness from Architeuthis Flux himself, and this MCP server is my way of paying it forward — a tool to make his hardware more accessible to anyone with an LLM and a breadboard idea. Hope it lights up your brain the way the V5 lights up mine.

Contributing

PRs, issues, and questions all welcome. See CONTRIBUTING.md for the workflow.

License

MIT — matches the Jumperless firmware.