mcjtag

JTAG/SWD MCP Server for hardware debugging via OpenOCD.

Gives LLMs the ability to interact with JTAG/SWD debug probes — read/write memory, inspect registers, flash firmware, scan JTAG chains, and decode SVD peripheral registers.

Documentation | PyPI

Install

uvx mcjtag

Or install permanently:

uv pip install mcjtag

Requirements: Python 3.11+, OpenOCD installed on your system.

Quick Start

# Auto-spawn OpenOCD with a config file
OPENOCD_CONFIG=openocd-daplink-swd.cfg uvx mcjtag

# Connect to an already-running OpenOCD
OPENOCD_HOST=localhost OPENOCD_PORT=6666 uvx mcjtag

# Add to Claude Code
claude mcp add mcjtag -- uvx mcjtag

# Add to Claude Code with auto-spawn
claude mcp add mcjtag -- env OPENOCD_CONFIG=/path/to/config.cfg uvx mcjtag

A typical first session:

1. probe_diagnostics() — verify probe, target, and connection health
2. jtag_scan() — enumerate the JTAG chain, read IDCODEs
3. target_state() — check if the target is halted or running
4. read_memory("0x08000000", count=4) — read the vector table
5. read_registers() — inspect all CPU registers

Tools

17 tools across 9 categories:

Resources

7 MCP resources for polling target state without tool calls:

Prompts

5 pre-built prompt templates for common workflows:

Environment Variables

Safety

mcjtag ships with conservative defaults for use alongside safety-critical firmware:

• Write restrictions — write_memory only allows SRAM by default (0x20000000-0x20100000). Flash, peripheral, and system writes are blocked unless you expand the ranges.
• Raw command deny-list — raw_command blocks destructive OpenOCD commands (flash erase, memory writes, reset, shutdown). Use dedicated tools instead, or set MCJTAG_ALLOW_RAW=true.
• Flash validation — flash_program checks file existence, extension, and size before writing.
• Input validation — Hex parsing rejects negatives, alignment is enforced for writes, values are range-checked against width.

Hardware

Tested with:

• Probe: Treedix DAP-Link V1 (CMSIS-DAP)
• Target: STM32F103C8T6 (Blue Pill)
• Transport: SWD and JTAG

Shipped OpenOCD configs:

• openocd-daplink-swd.cfg — DAP-Link over SWD (2-wire, recommended)
• openocd-daplink-jtag.cfg — DAP-Link over JTAG (4-wire, chain scanning)

License

MIT