Skip to main content
Glama
io.github.microhenrio/openocd-mcp

io.github.microhenrio/openocd-mcp

by microhenrio

OpenOCD MCP Server

Debug microcontrollers directly from your AI assistant. This is an MCP server that drives OpenOCD, letting any MCP-compatible AI flash firmware, control execution, and inspect a running target — and read your variables and peripheral registers by name instead of raw addresses.

Description

Once connected to a target through a debug probe (ST-Link, J-Link, CMSIS-DAP, …), your AI assistant can:

  • Flash firmware — program and verify .elf / .bin / .hex images

  • Control execution — halt, resume, single-step, reset

  • Inspect state — read/write CPU registers and memory

  • Set breakpoints — hardware & software, including conditional breakpoints (halt only when an expression is true) and hit-count breakpoints

  • Watch memory — hardware watchpoints that halt on read/write/access to an address

  • Read variables by name — from your firmware's .elf symbols (e.g. read_variable uart_rx_count)

  • Live-watch variables — a window that samples variables over time without halting the CPU, with expandable structs/arrays auto-typed from DWARF (signed/float/pointer/enum)

  • Read peripheral registers by name — from a CMSIS-SVD file, decoded into named bitfields (e.g. RCC.CR, GPIOA.MODER)

  • Safety gates — permission layer (read-only mode, gated flash-erase, flash path/size limits) so the agent can't damage a target unexpectedly

The server is chip-agnostic — it works with any target OpenOCD supports; you point it at your chip's config and (optionally) SVD/ELF. It can also start OpenOCD for you and download OpenOCD automatically for your platform, so there's nothing else to install by hand.

Related MCP server: dbgprobe-mcp-server

Supported AI clients

Any MCP-compatible client works. Tested and known to work:

Client

Platform

Claude Code

CLI / IDE

Claude Desktop

macOS / Windows

Cursor

IDE

Windsurf

IDE

Cline

VS Code extension

Continue

VS Code / JetBrains

Zed

Editor

VS Code + GitHub Copilot

IDE (agent mode)

Gemini CLI

CLI

Installation

Prerequisites: Python 3.10+ and a debug probe connected to your target.

Clone and install the package into a virtual environment:

git clone https://github.com/microhenrio/openocd-mcp
cd openocd-mcp
python -m venv .venv

Install it (creates the openocd-mcp command):

# Windows
.venv\Scripts\python -m pip install -e .

# macOS / Linux
.venv/bin/python -m pip install -e .

Windows shortcut: run setup.bat — it creates the environment, installs the package, and registers it with Claude Code automatically.

OpenOCD is obtained automatically: a build for your OS/architecture is downloaded and cached on first connect (checksum-verified). You can also fetch it ahead of time with openocd-mcp install-openocd, or use an existing install by setting the OPENOCD_BIN environment variable.

Registering with your AI client

The server executable is:

# Windows
<repo>\.venv\Scripts\openocd-mcp.exe

# macOS / Linux
<repo>/.venv/bin/openocd-mcp
# Windows
claude mcp add --scope user openocd -- "%CD%\.venv\Scripts\openocd-mcp.exe"

# macOS / Linux
claude mcp add --scope user openocd -- "$PWD/.venv/bin/openocd-mcp"

Restart Claude Code, then verify with claude mcp list.

Add to claude_desktop_config.json (Edit → Settings → Developer → Edit Config):

{
  "mcpServers": {
    "openocd": {
      "command": "/path/to/.venv/bin/openocd-mcp"
    }
  }
}

Restart Claude Desktop.

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in your project):

{
  "mcpServers": {
    "openocd": {
      "command": "/path/to/.venv/bin/openocd-mcp"
    }
  }
}

Restart Cursor.

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "openocd": {
      "command": "/path/to/.venv/bin/openocd-mcp"
    }
  }
}

Restart Windsurf.

Open the Cline panel → MCP Servers → Add Server → Manual, then enter:

{
  "openocd": {
    "command": "/path/to/.venv/bin/openocd-mcp"
  }
}

Add to ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "openocd",
      "command": "/path/to/.venv/bin/openocd-mcp"
    }
  ]
}

Add to .vscode/mcp.json in your workspace (or user settings.json):

{
  "servers": {
    "openocd": {
      "type": "stdio",
      "command": "/path/to/.venv/bin/openocd-mcp"
    }
  }
}

Enable via Chat → Agent mode in VS Code.

Updating

There's no self-update tool exposed over MCP — updating means running commands in a terminal, either yourself or by asking an AI that has shell access (e.g. Claude Code). After updating, restart your AI client so it loads the new server; if it was mid-session, it may need to stop the old openocd-mcp process first (a file lock can block the reinstall while it's running).

PyPI install (pip install openocd-mcp or uvx):

pip install -U openocd-mcp

# uvx caches by default — force a refresh:
uvx --refresh openocd-mcp

Editable git-clone install (what setup.bat / this repo's instructions set up):

git pull
# only needed if dependencies changed:
.venv/bin/python -m pip install -e .   # or .venv\Scripts\python on Windows

Check the installed version with pip show openocd-mcp.

How to work with it

1. Point it at your chip

Each firmware project tells the server which target it's debugging. Create an openocd-mcp.json in your project root (a template is in openocd-mcp.example.json):

{
  "target_cfg": "target/stm32g0x.cfg",
  "svd_file": "path/to/STM32G0B0.svd",
  "elf_file": "path/to/build/firmware.elf"
}
  • target_cfg / interface_cfg — OpenOCD configs (relative to its scripts dir). Defaults to an ST-Link probe; set target_cfg for your chip.

  • transport — "swd" or "jtag". Set "swd" for a J-Link on Cortex-M (with interface_cfg: "interface/jlink.cfg"); leave empty for ST-Link.

  • svd_file — CMSIS-SVD file for the chip (enables peripheral registers by name).

  • elf_file — your firmware build output (enables variables by name).

J-Link on Windows: OpenOCD reaches J-Links via libusb, so bind the J-Link's debug interface to libusbK (or WinUSB) with Zadig once (Interface 2 / MI_02). Newer SEGGER software (v7.x+) is compatible with libusbK, so both OpenOCD and SEGGER tools can coexist. ST-Link works without that step.

Or simply tell the AI the chip you're using and it will configure the session for you. show_config reports the active settings at any time.

2. Describe what you want

With the board plugged in, describe what you want — the AI picks the right tools:

You say…

What happens

"connect and halt the target"

Starts OpenOCD if needed, attaches, halts the CPU

"what's the status?"

Reports running/halted and the current program counter

"read the variable sensor_value"

Looks it up in the .elf and reads it off the chip

"set motor_enabled to 1"

Writes the variable by name

"watch tick_count live for 2 seconds"

Calls watch_variables — samples it repeatedly without halting and returns a table of values over time, right in the chat

"read GPIOA.MODER"

Reads the register and decodes its named bitfields

"list the RCC registers"

Lists registers from the SVD

"break at 0x08001234, then reset and run"

Sets a breakpoint and resets

"break at 0x08001234 when r0 is 42"

Sets a conditional breakpoint (using [get_reg r0] == 42)

"break at 0x08001234 after 5 hits"

Sets a hit-count breakpoint

"watch for writes to 0x20000000"

Sets a hardware data watchpoint

"flash build/firmware.elf and run it"

Programs, verifies, and restarts

"dump 64 bytes of RAM at 0x20000000"

Reads memory

You don't call tools by name — describe the goal and the AI maps it to the underlying tools.

3. Conditional breakpoints & watchpoints

Conditional breakpoints halt only when a condition holds — useful for catching one specific case in code that runs constantly. Conditions are TCL expressions and can use two helpers:

  • get_reg <name> — a CPU register value (e.g. get_reg r0, get_reg pc)

  • get_mem <addr> [width] — a memory value (e.g. get_mem 0x20000000)

Just describe the intent; the AI builds the condition:

You say…

Condition used

"break at 0x08001234 only when r0 > 100"

expr {[get_reg r0] > 100}

"break at parse_packet when the byte at 0x20000005 is 0xFF"

expr {[get_mem 0x20000005 8] == 0xFF}

"stop at 0x08001234 on the 10th time it's hit"

incr ::hits; expr {$::hits >= 10}

When the condition is false the server resumes automatically and keeps going until it's true (or you stop it).

Watchpoints halt the CPU when it accesses a memory location — ideal for finding what corrupts a variable:

  • "watch for writes to 0x20000000"

  • "watch address 0x20000010 for any read or write"

Live-watching variables

There are two separate ways to watch a variable without halting the CPU — one the AI can trigger, one you run yourself:

watch_variables (MCP tool)

openocd-watch (standalone GUI)

Triggered by

Asking the AI in chat

Running the command yourself in a terminal

Output

A text table of samples returned to the chat

A live-updating window with a tree view

Duration

One-shot: N samples, then it returns

Keeps running until you close it

Structs/arrays

Flat values only

Expandable, DWARF-typed

Ask the AI for a quick, bounded look at a value over time — "watch tick_count for 10 samples", "sample sensor_value every 200ms for 2 seconds". This calls the watch_variables tool directly; no extra setup needed beyond an ELF loaded.

Run the GUI yourself for an open-ended live view, especially of structs/arrays. It's a standalone app that opens its own connection to OpenOCD, so it works fine alongside any AI session driving the same target — but it is not an MCP tool, so the AI cannot open it for you; run it directly:

openocd-watch tick_count sensor_value --elf path/to/firmware.elf
# or, if elf_file is set in openocd-mcp.json:
openocd-watch tick_count sensor_value

It samples the variables without halting the CPU and refreshes a tree in a window. Add entries with the box (press Enter or Add) and remove a selected row with Remove (or the Delete key). Each entry is resolved automatically and can be:

  • a variable name (uwTick, commsService) → looked up in the ELF; if it's a struct, union, or array it gets an expand triangle, and its members/elements are shown auto-typed from DWARF (signed, float, pointer, enum, bitfields, nested structs). Enums show the symbolic name (STATE_HEATING (1)), and C bitfields show just their own bit(s) rather than the whole storage word;

  • a hex address with optional size (0x20000000, 0x20000000:2) → read directly.

A Format dropdown switches how values are shown — Auto (by C type) / Hex / Decimal / Signed / Float (f32) / Binary — and re-renders instantly. Use --interval to change the poll rate, --format to set the initial format, or --samples N for a headless printout. Requires Tkinter (ships with standard Python) and a debug build (-g) for the type info.

If OpenOCD isn't already running, add --autostart and the window launches it for you (and stops it on close) — fully standalone, no AI client or .bat needed:

openocd-watch uwTick xTickCount --elf path/to/firmware.elf --autostart --target target/stm32g0x.cfg

CPU core registers (r0, pc, sp, …) require the target to be halted — the AI halts first when needed. Memory, variables, and peripheral registers are memory-mapped and can be read while the CPU is running (as the live-watch window does). The first connect of a session starts OpenOCD automatically.

Safety / permissions

Mutating operations are gated so the agent can't damage a target unexpectedly. Reads are always allowed; the gates apply to writes, flashing, erasing, and the raw-command escape hatch.

Permission

Default

Gates

read_only

false

master switch — blocks all writes/flash/erase/raw

allow_memory_write

true

write_memory, write_variable, write_register, write_peripheral_register

allow_flash

true

flash_write (program)

allow_flash_erase

false

flash_erase_sector (destructive — opt in)

allow_raw_command

true

run_command (can bypass other limits)

flash_allowed_paths

[] (any)

restrict flash_write to files under these dirs

flash_max_bytes

0 (no limit)

reject flashing files larger than this

Set them three ways (later wins):

  1. A permissions object in openocd-mcp.json (see openocd-mcp.example.json).

  2. The set_permissions tool at runtime — e.g. ask the AI to "make the target read-only" or "allow flash erase for this session".

  3. The OPENOCD_MCP_READONLY=1 environment variable (forces read-only).

A blocked call returns a clear BLOCKED: … message explaining which permission to enable. show_config lists the active permissions.

Available Tools

39 tools
add_breakpointB

Add a breakpoint. address : hex address, e.g. '0x08001234' hardware : True for hardware breakpoint (recommended for flash); False for software

Inputs: address (required), hardware. Returns: result

add_conditional_breakpointA

Add a conditional breakpoint. The target halts at address only if condition evaluates true; otherwise resume/reset-run skips past it.

address : hex address for the breakpoint condition : a TCL expression/block. Use get_reg and get_mem ?width?. It is evaluated when the breakpoint is hit; non-zero = halt.

Examples: 'expr {[get_reg r0] > 100}' 'expr {[get_mem 0x20000000] == 0xdeadbeef}' 'incr ::hit_count; expr {$::hit_count >= 5}'

Inputs: address (required), condition (required). Returns: result

add_watchpointC

Add a data watchpoint. address : hex address to watch length : size in bytes (usually 1, 2, or 4) type : 'r' (read), 'w' (write), or 'a' (access/any) value : optional hex value to match (hardware dependent) mask : optional hex mask for the value match

Inputs: address (required), mask, type, value, +1 more. Returns: result

configureA

Set the chip/project settings for this session. Only non-empty arguments are applied; the rest keep their current values.

interface_cfg : debug-probe OpenOCD config, e.g. 'interface/stlink.cfg' or 'interface/jlink.cfg' target_cfg : chip OpenOCD config, e.g. 'target/stm32g0x.cfg' transport : 'swd' or 'jtag' — set 'swd' for J-Link on Cortex-M (else it picks JTAG) svd_file : path to the chip's CMSIS-SVD file (peripheral registers) elf_file : path to the firmware .elf (variables by name)

Alternatively, put these in an 'openocd-mcp.json' file in your project so they load automatically. Loading a new SVD/ELF takes effect on next use.

Inputs: elf_file, svd_file, transport, target_cfg, +1 more. Returns: result

connectA

Connect to OpenOCD. Call this first.

If nothing is listening and auto_start is True, the server launches OpenOCD itself using the configured project settings (probe + target) and connects. Set auto_start=False to require an already-running OpenOCD.

Inputs: host, port, auto_start. Returns: result

flash_erase_sectorA

Erase a range of flash sectors. bank : flash bank index (usually 0) first : first sector number to erase last : last sector number to erase (inclusive)

Inputs: bank (required), last (required), first (required). Returns: result

flash_infoB

Display information about the flash bank (size, sectors, erase state).

Inputs: bank. Returns: result

flash_writeA

Program a firmware file onto the target flash. path : full path to .elf, .bin, or .hex file verify : read back and verify after programming (recommended) reset_after : reset and run the new firmware after flashing

Inputs: path (required), verify, reset_after. Returns: result

haltA

Halt the target CPU so registers and memory can be inspected.

Inputs: no named parameters. Returns: result

install_openocdA

Download and cache OpenOCD for this OS/architecture (if not already present), so the server can run without a separate OpenOCD install. Verifies a pinned SHA-256. Needed only when OpenOCD isn't bundled or on PATH (e.g. a pip install).

Inputs: no named parameters. Returns: result

list_breakpointsA

List all currently set breakpoints and watchpoints.

Inputs: no named parameters. Returns: result

list_peripheral_registersA

With no argument: list all peripheral names. With a peripheral name (e.g. 'RCC'): list that peripheral's registers.

Inputs: peripheral. Returns: result

list_variablesA

List known variable names, optionally filtered by a substring.

Inputs: filter. Returns: result

load_elfA

Load variable names and addresses from a firmware .elf file, so you can read and write variables by name. Build the firmware with debug symbols. path: full path to the .elf (defaults to the configured elf_file if set).

Inputs: path. Returns: result

load_svdA

Load peripheral register definitions from a CMSIS-SVD file. Loaded automatically on first use from the configured svd_file; call this only to use a different SVD. path defaults to the configured svd_file.

Inputs: path. Returns: result

read_memoryB

Read memory from the target. address : hex address, e.g. '0x20000000' count : number of units to read width : unit size in bits — 8, 16, or 32

Inputs: address (required), count, width. Returns: result

read_peripheralB

Read memory-mapped peripheral registers. base_address : peripheral base, e.g. '0x40020000' for GPIOA on STM32 count : number of 32-bit registers to read (default 16)

Inputs: base_address (required), count. Returns: result

read_peripheral_registerA

Read a peripheral register by name (e.g. 'RCC.CR', 'GPIOA.MODER') and decode its named bitfields. The target should be halted for a stable read.

Inputs: name (required). Returns: result

read_registerA

Read a single CPU register by name. Examples: 'r0', 'pc', 'sp', 'lr', 'xpsr', 'msp', 'psp'

Inputs: name (required). Returns: result

read_registersA

Dump all CPU registers (r0-r15, pc, sp, lr, xpsr, etc.).

Inputs: no named parameters. Returns: result

read_variableB

Read a global/static variable by name (requires load_elf first). Scalars (1/2/4 bytes) are decoded to hex and decimal; larger objects (arrays, structs) are dumped as words.

Inputs: name (required). Returns: result

remove_all_breakpointsA

Remove every breakpoint and watchpoint that is currently set.

Inputs: no named parameters. Returns: result

remove_breakpointC

Remove the breakpoint at the given address.

Inputs: address (required). Returns: result

remove_conditional_breakpointB

Remove the conditional breakpoint at the given address.

Inputs: address (required). Returns: result

remove_watchpointC

Remove the watchpoint at the given address.

Inputs: address (required). Returns: result

resetA

Reset the target. mode: 'halt' — reset and immediately halt (good for debugging) 'run' — reset and start running 'init' — reset and run init scripts With 'run' and conditional breakpoints set, this honors those conditions (skipping false ones) just like resume.

Inputs: mode. Returns: result

resumeA

Resume CPU execution. Optionally resume from a specific address. If conditional breakpoints are set, this skips past those whose condition is false and stops at the first one whose condition is true (or on any other halt).

Inputs: address. Returns: result

run_commandA

Run any raw OpenOCD TCL command and return its output. Use this for anything not covered by the other tools.

Inputs: command (required). Returns: result

set_permissionsA

Adjust safety permissions for this session (only provided args change).

read_only : master switch — blocks all writes/flash/erase/raw allow_memory_write : write_memory / write_variable / write_register / write_peripheral_register allow_flash : flash_write (program) allow_flash_erase : flash_erase_sector (destructive; off by default) allow_raw_command : run_command escape hatch flash_max_bytes : reject flashing files larger than this (0 = no limit)

For persistent settings, put a "permissions" object in openocd-mcp.json. (flash_allowed_paths is set there, not here.)

Inputs: read_only, allow_flash, flash_max_bytes, allow_flash_erase, +2 more. Returns: result

show_configA

Show the current effective project settings and where they came from.

Inputs: no named parameters. Returns: result

start_openocdA

Start OpenOCD as a subprocess (so you don't have to launch it manually). Detects an already-running instance and won't start a duplicate.

interface_cfg : debug-probe config (default: project setting, else ST-Link) target_cfg : chip config, e.g. 'target/stm32f4x.cfg' (default: project setting) Leave both empty to use the configured project settings (see configure / openocd-mcp.json). A target_cfg must be set somewhere or this errors.

Inputs: target_cfg, interface_cfg. Returns: result

statusA

Report current debug state: whether OpenOCD is running, whether the target is halted or running, and the current program counter (PC) if halted. Does not disturb execution.

Inputs: no named parameters. Returns: result

stepB

Execute a single instruction and halt again.

Inputs: no named parameters. Returns: result

stop_openocdA

Stop the OpenOCD process this server started.

Inputs: no named parameters. Returns: result

watch_variablesA

Live-watch one or more variables WITHOUT halting the CPU: sample them repeatedly while the target runs and return a time-series table.

names : comma- or space-separated variable names (requires load_elf). samples : number of snapshots, 1-200. interval_ms : delay between snapshots in milliseconds.

Works for RAM globals/statics (read live via background memory access). CPU registers need a halt and aren't supported here. Multi-word values are read non-atomically, so a >4-byte value may be momentarily inconsistent.

This tool is one-shot and returns a flat text table. For an open-ended, auto-refreshing GUI window with expandable structs/arrays, there is a separate standalone program called openocd-watch. It is NOT reachable through this MCP server as a tool call — but it is an ordinary console script, so an assistant with its own shell/process-launch capability (e.g. a coding agent with a terminal tool) MAY run it directly as a background process for the user, same as it would run any other CLI program. An assistant limited to this server's MCP tools cannot reach it and should tell the user to run it themselves instead. Invocation: openocd-watch --elf <path/to/firmware.elf> Add --autostart if OpenOCD isn't already running.

Inputs: names (required), samples, interval_ms. Returns: result

write_memoryB

Write a value to a memory address. address : hex address, e.g. '0x20000000' value : hex value, e.g. '0xDEADBEEF' width : 8, 16, or 32

Inputs: value (required), address (required), width. Returns: result

write_peripheral_registerA

Write a 32-bit value to a peripheral register by name (e.g. 'GPIOA.ODR').

Inputs: name (required), value (required). Returns: result

write_registerC

Write a value to a CPU register. value: hex string, e.g. '0x20001000'

Inputs: name (required), value (required). Returns: result

write_variableA

Write a scalar global/static variable by name (requires load_elf first). value: hex (e.g. '0x2A') or decimal. Use write_memory for arrays/structs.

Inputs: name (required), value (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 39 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose, from setting breakpoints and watchpoints to reading/writing memory, registers, peripherals, and variables. There is no overlapping functionality; even the raw command escape hatch is explicitly for uncovered operations.

    Naming Consistency5/5

    All tools follow a consistent verb_noun or verb_noun pattern using snake_case (e.g., add_breakpoint, read_memory, flash_write). Single-word verbs like halt and reset are common for core actions. The naming makes tool selection intuitive.

    Tool Count4/5

    With 39 tools, the count is high but justified by the broad scope of microcontroller debugging (breakpoints, watchpoints, memory, registers, peripherals, variables, flashing, configuration, etc.). It covers all typical needs without being bloated, though a few tools could be combined.

    Completeness5/5

    The tool surface covers all essential debugging operations: breakpoints (including conditional and watchpoints), memory/register/peripheral access, variable read/write with ELF symbol loading, flashing, reset, resume, step, status, configuration, permissions, and a raw command escape hatch. No critical gaps are apparent.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server that exposes GDB debugging as tools. An AI assistant can set breakpoints, run programs, step through code, inspect variables and memory, and examine registers — all via structured tool calls. Reverse debugging with rr is also supported.
      34
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Stateful MCP server for driving debug probes (J-Link) to flash, debug, and inspect embedded targets. Enables AI agents to perform flash, memory, breakpoint, and ELF/SVD-aware operations conversationally.
      41
      11
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants like Claude to directly debug microcontrollers via JLink, supporting breakpoints, single-step, memory/register access, variable inspection, RTT logging, and firmware flashing.
      25
      7
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      A headless MCP server that enables AI tools (like Claude Code) to read and analyze serial logs from embedded boards (ESP32, STM32) for firmware debugging, with read-only tools for log retrieval and a built-in web viewer.
      6
      1
      -