---
title: mcjtag
description: JTAG/SWD debugging through the Model Context Protocol
template: splash
hero:
  tagline: Hardware debugging meets the Model Context Protocol. Inspect registers, decode peripherals, flash firmware — all through natural language.
  image:
    file: ../../assets/hero.png
    alt: JTAG debugger connected to a microcontroller via TCK, TMS, TDO, and GND lines
  actions:
    - text: Get Started
      link: /tutorials/getting-started/
      icon: right-arrow
      variant: primary
    - text: Tool Reference
      link: /reference/tools/
      variant: minimal
---

import { Card, CardGrid } from '@astrojs/starlight/components';

## What mcjtag does

<CardGrid stagger>
  <Card title="Probe and Scan">
    Detect debug probes, enumerate JTAG chains, and identify connected chips by IDCODE.
    Supports DAP-Link, ST-Link, J-Link, and FTDI-based adapters through OpenOCD.
  </Card>
  <Card title="Memory and Registers">
    Read and write memory with hexdump formatting, access all CPU registers,
    and search memory for byte patterns. Alignment and range validation built in.
  </Card>
  <Card title="SVD Peripheral Decoding">
    Load CMSIS SVD files to decode peripheral registers down to individual bitfields.
    See exactly what GPIOA, USART1, or RCC are doing without consulting the datasheet.
  </Card>
  <Card title="Flash Programming">
    Program firmware images (.bin, .hex, .elf) with erase and verify steps,
    progress reporting, and file validation. Safe by default.
  </Card>
</CardGrid>

## Quick start

```bash
# Install and run
uvx mcjtag

# Or with auto-spawned OpenOCD
OPENOCD_CONFIG=openocd-daplink-swd.cfg uvx mcjtag
```

A typical first session looks like this:

```
probe_diagnostics()             # verify everything works (9-point health check)
jtag_scan()                     # see what's on the chain
target_state()                  # check if halted or running
read_memory("0x08000000", 4)    # read the vector table
read_registers()                # see CPU state
```

The LLM sees structured responses for each call — addresses, hex values, decoded
bitfields, formatted hexdumps — and can reason about the hardware state from there.

## 17 tools across 9 categories

| Category | Tools | Purpose |
|---|---|---|
| Connection | `connect`, `start_openocd`, `disconnect` | Connect to or spawn OpenOCD, tear down sessions |
| Diagnostics | `probe_diagnostics` | 9-point health check of probe, target, and capabilities |
| Target | `target_state`, `target_control` | Halt, resume, step, reset, query execution state |
| Memory | `read_memory`, `write_memory`, `search_memory` | Read with hexdump, write (SRAM-safe), byte pattern search |
| Registers | `read_registers`, `write_register` | Read all or specific CPU registers, write individual registers |
| Flash | `flash_info`, `flash_program` | Bank topology, program firmware with erase/verify |
| JTAG | `jtag_scan`, `jtag_shift` | Chain enumeration, raw IR/DR scan operations |
| SVD | `svd_inspect` | Load SVD files, list peripherals, decode register bitfields |
| Raw | `raw_command` | Direct OpenOCD TCL command escape hatch |

Plus **7 resources** for polling live state without tool calls (`jtag://target/state`,
`jtag://registers/all`, `jtag://flash/banks`, and more) and **5 prompts** that guide
the LLM through common workflows like crash debugging and chip identification.

## Safety by default

mcjtag is built for use alongside safety-critical firmware. It ships with conservative
defaults that prevent accidental damage to your target:

- **Memory writes restricted to SRAM** by default (0x20000000-0x20100000). Flash,
  peripherals, and system registers are protected unless you explicitly widen the range.
- **Destructive OpenOCD commands blocked** in `raw_command` mode. Flash writes, memory
  writes, resets, and TCL metaprogramming are caught by a deny-list.
- **Flash programming validates files** before writing — checks existence, extension,
  and size. Progress is reported through erase, write, and verify phases.
- **All safety rails are configurable** via environment variables. See the
  [Safety Configuration](/guides/safety-configuration/) guide for details.

---

*Hero image: [Arshon Technology](https://arshon.com)*
