OpenOCD Debugger

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

\.venv\Scripts\openocd-mcp.exe

macOS / Linux

/.venv/bin/openocd-mcp

Claude Code

# 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.

Claude Desktop

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

{

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

Restart Claude Desktop.

Cursor

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

{

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

Restart Cursor.

Windsurf

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

{

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

Restart Windsurf.

Cline (VS Code)

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

{

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

Continue (VS Code / JetBrains)

Add to ~/.continue/config.json:

{

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

VS Code + GitHub Copilot

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 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 — a CPU register value (e.g. get_reg r0, get_reg pc)
• get_mem [width] — a memory value (e.g. get_mem 0x20000000)

Just describe the intent; the AI builds the condition:

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:

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 se