# jumperless-mcp
[](https://crates.io/crates/jumperless-mcp)
[](https://docs.rs/jumperless-mcp)
[](https://github.com/LesbianVelociraptor/jumperless-mcp/actions)
[](https://opensource.org/licenses/MIT)
> A [Model Context Protocol](https://modelcontextprotocol.io) server for the
> [Jumperless V5](https://www.jumperless.org) 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](https://github.com/LesbianVelociraptor/jumperless-mcp/releases/latest).
Archive names follow the pattern `jumperless-mcp-<version>-<platform>-<arch>.<ext>`:
| 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):**
```bash
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):**
```bash
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](https://rustup.rs)):
```bash
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`:
```bash
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:
```bash
claude mcp add jumperless jumperless-mcp
```
Or edit `~/.claude.json` (user-level) or `.mcp.json` (project-level) directly:
```json
{
"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`
```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
```bash
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
```bash
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
```bash
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)
```bash
--port COMx # explicit serial port (auto-detected by default)
--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):
```bash
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:
| **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](https://docs.jumperless.org/12-llm-tools-specification.html)
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](https://github.com/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](https://github.com/LesbianVelociraptor/jumperless-mcp/commits/main).
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](CONTRIBUTING.md)
for the workflow.
---
## License
MIT — matches the [Jumperless firmware](https://github.com/Architeuthis-Flux/JumperlessV5).