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.

Supported AI clients

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

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"

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

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

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

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

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

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

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 don't call tools by name — describe the goal and the AI maps it to the underlying tools.

3. Conditional breakpoints & watchpoints