io.github.microhenrio/openocd-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@io.github.microhenrio/openocd-mcp flash build/firmware.elf and run"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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/.heximagesControl 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
.elfsymbols (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 |
CLI / IDE | |
macOS / Windows | |
IDE | |
IDE | |
VS Code extension | |
VS Code / JetBrains | |
Editor | |
IDE (agent mode) | |
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 .venvInstall 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-mcpEditable 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 WindowsCheck 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; settarget_cfgfor your chip.transport—"swd"or"jtag". Set"swd"for a J-Link on Cortex-M (withinterface_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 | Looks it up in the |
"set | Writes the variable by name |
"watch | Calls |
"read | Reads the register and decodes its named bitfields |
"list the | Lists registers from the SVD |
"break at | Sets a breakpoint and resets |
"break at | Sets a conditional breakpoint (using |
"break at | Sets a hit-count breakpoint |
"watch for writes to | Sets a hardware data watchpoint |
"flash | Programs, verifies, and restarts |
"dump 64 bytes of RAM at | 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 |
|
"break at |
|
"stop at |
|
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
0x20000010for 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:
|
| |
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_valueIt 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.cfgCPU 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 firstconnectof 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 |
|
| master switch — blocks all writes/flash/erase/raw |
|
|
|
|
|
|
|
|
|
|
|
|
|
| restrict |
|
| reject flashing files larger than this |
Set them three ways (later wins):
A
permissionsobject inopenocd-mcp.json(seeopenocd-mcp.example.json).The
set_permissionstool at runtime — e.g. ask the AI to "make the target read-only" or "allow flash erase for this session".The
OPENOCD_MCP_READONLY=1environment 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 toolsadd_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
Scored across 39 tools
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.
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.
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.
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
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
The OpenRouter MCP server plugs OpenRouter into the AI tools you already use. Once connected, your assistant can pull live OpenRouter data (models, prices, your credits, rankings, and docs) and send quick test messages, all without leaving your editor.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP 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.343MIT
- AlicenseAqualityDmaintenanceStateful 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.4111MIT
- AlicenseAqualityDmaintenanceEnables AI assistants like Claude to directly debug microcontrollers via JLink, supporting breakpoints, single-step, memory/register access, variable inspection, RTT logging, and firmware flashing.257MIT
- FlicenseAqualityDmaintenanceA 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.61-