jlink-mcp

<p align="center"> <img src="logo.png" alt="jlink-mcp logo" width="200"> </p> <h1 align="center">jlink-mcp</h1> <p align="center"> <strong>Give AI hands to touch silicon.</strong><br> An MCP server that lets LLMs debug embedded devices through SEGGER J-Link probes. </p> <p align="center"> <img src="https://img.shields.io/badge/MCP-Server-blue?style=for-the-badge" alt="MCP Server"> <img src="https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript"> <img src="https://img.shields.io/badge/J--Link-SEGGER-00979D?style=for-the-badge" alt="J-Link"> <img src="https://img.shields.io/badge/ARM-Cortex--M-0091BD?style=for-the-badge" alt="ARM Cortex-M"> </p> <p align="center"> <a href="https://github.com/Klievan/jlink-mcp/stargazers"><img src="https://img.shields.io/github/stars/Klievan/jlink-mcp?style=flat-square" alt="GitHub Stars"></a> <a href="https://github.com/Klievan/jlink-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Klievan/jlink-mcp?style=flat-square" alt="License"></a> <a href="https://www.npmjs.com/package/jlink-mcp"><img src="https://img.shields.io/npm/v/jlink-mcp?style=flat-square&color=cb0000" alt="npm"></a> <a href="https://www.npmjs.com/package/jlink-mcp"><img src="https://img.shields.io/npm/d18m/jlink-mcp?style=flat-square&color=cb0000" alt="npm downloads"></a> <a href="https://marketplace.visualstudio.com/items?itemName=Klievan.jlink-mcp"><img src="https://img.shields.io/badge/VS%20Code-Marketplace-007ACC?style=flat-square&logo=visualstudiocode&logoColor=white" alt="VS Code Marketplace"></a> <a href="https://github.com/Klievan/jlink-mcp/releases/latest"><img src="https://img.shields.io/github/v/release/Klievan/jlink-mcp?style=flat-square" alt="Latest release"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-green?style=flat-square" alt="MCP Compatible"></a> <a href="https://github.com/Klievan/jlink-mcp/actions/workflows/ci.yml"><img src="https://github.com/Klievan/jlink-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://github.com/Klievan/jlink-mcp/actions/workflows/hil.yml"><img src="https://img.shields.io/badge/tested%20on-real%20nRF52840-brightgreen?style=flat-square" alt="Hardware tested"></a> </p>

---

See it work

<p align="center"> <img src="demo/jlink-mcp-demo.gif" alt="A terminal session: the MCP server finds the probe, flashes firmware, opens a debug session, streams RTT logs, injects a fault, and decodes the resulting HardFault — naming the faulting instruction." width="100%"> </p> <p align="center"> <em>Real MCP tool calls against a real nRF52840-DK. Reproduce it yourself: <code>npm run demo</code></em> </p>

Your firmware just crashed. One tool call:

> diagnose_crash

## Crash Diagnosis

### CPU State
Core: PC=0x000000B8 SP=0x2003FFA8 R0=0x0000000A R1=0x000007FF R2=0x00000001 ...
Status: XPSR=0x21000003 CONTROL=0x00000000 PRIMASK=0x00000000 ...
Stack: MSP=0x2003FFA8 PSP=0x00000000

⚠ CPU is in exception handler (IPSR=0x00000003)

### Fault Registers
CFSR=0x01000000 HFSR=0x40000000 DFSR=0x00000000 MMFAR=0xe000edf8 BFAR=0xe000edf8

### Decoded Faults
## UsageFault (UFSR):
  - UNALIGNED: Unaligned memory access
## HardFault (HFSR):
  - FORCED: Forced HardFault (escalated from configurable fault)

### Exception Stack Frame
  R0    = 0x0000000A     R1  = 0x000007FF
  R12   = 0x00000000     LR  = 0x000001F5
  PC    = 0x00000254     xPSR = 0x21000000

→ Faulting instruction at PC=0x00000254

### Recent Errors/Warnings from RTT
  [WRN] sensor_drv: sample out of range, clamping seq=2

Fault decoded, exception frame unwound, faulting instruction named, and the device's own log correlated — from one call, without a human reading a datasheet to find out what bit 24 of CFSR means.

And it knows what the silicon is

Point it at your target's CMSIS-SVD file and peripheral registers stop being hex:

> read_peripheral FICR

FICR @ 0x10000000
INFO.PART @ 0x10000100 = 0x00052840  (read-only)
  [31:0]    PART             0x52840 → N52840
INFO.RAM @ 0x1000010C = 0x00000100  (read-only)
  [31:0]    RAM              0x100 → K256
INFO.FLASH @ 0x10000110 = 0x00000400  (read-only)
  [31:0]    FLASH            0x400 → K1024

0x400 means 1024 KB of flash — but only if you know that, and an LLM guessing at bit layouts is exactly the failure this avoids. The addresses come from the vendor's own description, and the meanings from its enumerations.

Both transcripts are verbatim output from an nRF52840-DK in this project's hardware test suite.

What is this?

jlink-mcp connects AI assistants (Claude, Copilot, etc.) to your embedded hardware via SEGGER J-Link debug probes using the Model Context Protocol.

Instead of manually typing J-Link commands, your AI assistant can:

• Read registers and memory to understand device state
• Flash firmware and reset devices
• Stream RTT logs and search them by level/module/regex
• Diagnose crashes by auto-decoding ARM Cortex-M fault registers
• Control execution — halt, step, resume, breakpoints
• Start GDB servers for full debugging sessions

Also supports OpenOCD (ST-Link, CMSIS-DAP, FTDI) and Black Magic Probe backends.

Installing

You need the SEGGER J-Link software — that is what this server drives — a probe connected to an ARM Cortex-M target, and Node 18+. For the other backends, OpenOCD or arm-none-eabi-gdb instead.

Claude Code — from the plugin marketplace. This brings the embedded-debugging skill along with the server, which is what stops an assistant guessing at your hardware:

/plugin marketplace add Klievan/jlink-mcp
/plugin install jlink-mcp

Any other agent — point it at this repository and ask it to set itself up:

Install the MCP server at https://github.com/Klievan/jlink-mcp and configure it for my board.

It will find what it needs here. If you would rather do it by hand, the server is on npm and needs no build step: npx -y jlink-mcp, with JLINK_DEVICE set to your target. mcp-config.json is a config you can paste.

VS Code — install the extension. It registers the server for Copilot Chat, Claude, and any MCP-aware client, so there is nothing to configure.

Nix / NixOS — run directly from the flake without installing:

# Run standalone MCP server
nix run github:Klievan/jlink-mcp

# Or in an MCP client configuration (e.g. Claude Desktop / Claude Code)
# "command": "nix", "args": ["run", "github:Klievan/jlink-mcp", "--"]

Or add jlink-mcp and jlink-mcp-skills to your system configuration or flake:

# flake.nix inputs
inputs.jlink-mcp.url = "github:Klievan/jlink-mcp";

# In your packages:
inputs.jlink-mcp.packages.''${system}.jlink-mcp
inputs.jlink-mcp.packages.''${system}.jlink-mcp-skills

Note for NixOS users: Add your preferred probe tools (segger-jlink / segger-jlink-headless, openocd, or gdb) to environment.systemPackages or your devShell. segger-jlink requires nixpkgs.config.allowUnfree = true; and services.udev.packages = [ pkgs.segger-jlink ]; for probe USB permissions.

Then check it

Ask for check_setup. One call, and it says what is missing and what to do:

Not ready to debug yet.

OK    probe software — J-Link software found at /Applications/SEGGER/JLink
BLOCK probe — none detected (Connecting to J-Link via USB...FAILED). Check the USB cable.
BLOCK target device — not set. Find the exact name with search_devices, then set_device.
note  SVD — not loaded, so peripheral reads stay raw hex. Set SVD_PATH to a CMSIS-SVD file.

You do not need your device's exact part number up front. search_devices searches all 9800 that J-Link supports, by part number, manufacturer, or core.

Tools (48)

Workflow Tools (start here)

| Tool | Description | |------|-------------| | start_debug_session | One-call setup. Starts GDB server + connects RTT + returns boot log. | | snapshot | Captures full device state: registers, fault status, stack dump, RTT output. | | diagnose_crash | Auto-reads and decodes ARM Cortex-M fault registers (CFSR, HFSR, MMFAR, BFAR) with exception stack frame. |

Device Setup

| Tool | Description | |------|-------------| | list_devices | Scan for connected probes and show the configured target | | set_device | Change the target device at runtime — no restart needed | | set_serial_number | Change the probe serial number at runtime (for multi-probe setups) | | get_config | Current probe, target device, and GDB server state |

Device Control

| Tool | Description | |------|-------------| | device_info | Probe type, target CPU, compact register summary | | halt | Halt CPU | | resume | Resume CPU | | reset | Reset device. halt stops it at the reset vector; strategy picks a J-Link reset type, or omit it and let J-Link choose | | step | Single-step one instruction |

Peripherals (CMSIS-SVD)

Set jlinkMcp.svdPath to your target's SVD — the same file Cortex-Debug takes as svdFile. Vendors publish one per part.

| Tool | Description | |------|-------------| | list_peripherals | Every peripheral and base address on the chip | | read_peripheral | Read a peripheral's registers and decode each one's bit fields by name | | decode_register | Decode one register — read from the device, or interpret a value you already have |

Memory & Registers

| Tool | Description | |------|-------------| | read_memory | Read memory at address (clean hex dump output) | | write_memory | Write 32-bit value to address | | read_registers | All CPU registers in compact format | | read_register | Read specific register (PC, SP, R0-R12, etc.) |

Flash

| Tool | Description | |------|-------------| | flash | Flash .hex/.bin/.elf firmware to device | | erase | Erase entire flash |

Breakpoints

| Tool | Description | |------|-------------| | set_breakpoint | Set hardware breakpoint at address | | clear_breakpoints | Clear all breakpoints |

GDB Server

| Tool | Description | |------|-------------| | gdb_server_start | Start probe's GDB server | | gdb_server_stop | Stop GDB server + disconnect RTT | | gdb_server_status | GDB server, RTT, and proxy status |

Source-Level Debugging

Attach a real GDB client for symbol-aware work — backtraces, variable inspection, and stepping by source line rather than by instruction.

| Tool | Description | |------|-------------| | gdb_connect | Attach a GDB client (auto-starts the server; optional ELF for symbols) | | gdb_load | Load an ELF for debug symbols, optionally flashing it too | | gdb_backtrace | Call stack, optionally with locals in each frame | | gdb_command | Run any GDB command — print sensor_state, info threads, break main | | gdb_wait | Wait for the target to stop (after a continue or a breakpoint) | | gdb_disconnect | Detach the client, clearing breakpoints and debug hardware |

RTT (Real-Time Transfer)

| Tool | Description | |------|-------------| | rtt_connect | Connect to RTT telnet port | | rtt_disconnect | Disconnect from RTT | | rtt_read | Read recent log lines (ANSI stripped, Zephyr format parsed) | | rtt_search | Filter logs by level (err/wrn/inf/dbg), module, or regex | | rtt_send | Send data to device via RTT down-channel | | rtt_clear | Clear RTT buffer |

Telnet Proxy (Trice / Pigweed)

| Tool | Description | |------|-------------| | telnet_proxy_start | Start TCP proxy that tees RTT for external detokenizers | | telnet_proxy_stop | Stop proxy | | telnet_proxy_status | Proxy connection status | | `te