OpenOCD Debugger — Claude Code MCP server: setup and features
OpenOCD Debugger is an MCP server that brings microcontroller debugging into Claude Code. It inspects peripheral registers, sets breakpoints, and flashes firmware directly from chat prompts.
MIT ★ 5 updated 2026-07-02
claude mcp add --env OPENOCD_BIN=<OPENOCD_BIN> --env OPENOCD_MCP_CONFIG=<OPENOCD_MCP_CONFIG> --env OPENOCD_MCP_READONLY=<OPENOCD_MCP_READONLY> --transport stdio openocd-debugger -- uvx openocd-mcpWhat OpenOCD Debugger does
This server drives OpenOCD through hardware debug probes such as ST-Link, J-Link, or CMSIS-DAP. It allows an AI agent to flash .elf, .bin, and .hex files, halt target cores, single-step execution, and reset hardware.
Instead of raw memory addresses, the agent inspects variables by symbol name using ELF files and decodes peripheral registers via CMSIS-SVD files. It configures hardware watchpoints and conditional breakpoints, while safety controls prevent accidental flash erase operations.
Operation requires Python 3.10+ and a connected debug adapter. OpenOCD binaries download automatically during the initial connection, or you can point to an existing build via OPENOCD_BIN.
What it helps with
- flash firmware images in
.elf,.bin, or.hexformat - halt, single-step, and reset microcontrollers via hardware probes
- read variable values by symbol name from ELF files
- decode peripheral bitfields using CMSIS-SVD descriptions
Example prompts for the agent
- Flash
build/app.binto the connected board and issue a reset - Add a conditional breakpoint on
rx_buffer_overflowand halt on hit - Read the bitfields of
RCC.CRaccording to our chip SVD file
How to install OpenOCD Debugger
Platform CLI
claude mcp add --env OPENOCD_BIN=<OPENOCD_BIN> --env OPENOCD_MCP_CONFIG=<OPENOCD_MCP_CONFIG> --env OPENOCD_MCP_READONLY=<OPENOCD_MCP_READONLY> --transport stdio openocd-debugger -- uvx openocd-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from openocd-mcp <command>
Platform CLI
codex mcp add openocd-debugger --env OPENOCD_BIN=<OPENOCD_BIN> --env OPENOCD_MCP_CONFIG=<OPENOCD_MCP_CONFIG> --env OPENOCD_MCP_READONLY=<OPENOCD_MCP_READONLY> -- uvx openocd-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from openocd-mcp <command>
Config file
{
"mcpServers": {
"openocd-debugger": {
"command": "uvx",
"args": [
"openocd-mcp"
],
"env": {
"OPENOCD_BIN": "<OPENOCD_BIN>",
"OPENOCD_MCP_CONFIG": "<OPENOCD_MCP_CONFIG>",
"OPENOCD_MCP_READONLY": "<OPENOCD_MCP_READONLY>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from openocd-mcp <command>
Config file
{
"servers": {
"openocd-debugger": {
"type": "stdio",
"command": "uvx",
"args": [
"openocd-mcp"
],
"env": {
"OPENOCD_BIN": "<OPENOCD_BIN>",
"OPENOCD_MCP_CONFIG": "<OPENOCD_MCP_CONFIG>",
"OPENOCD_MCP_READONLY": "<OPENOCD_MCP_READONLY>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from openocd-mcp <command>
Platform CLI
gemini mcp add -e OPENOCD_BIN=<OPENOCD_BIN> -e OPENOCD_MCP_CONFIG=<OPENOCD_MCP_CONFIG> -e OPENOCD_MCP_READONLY=<OPENOCD_MCP_READONLY> openocd-debugger uvx openocd-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from openocd-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about OpenOCD Debugger
How to install OpenOCD Debugger in Claude Code?
Run claude mcp add openocd-mcp -- uvx openocd-mcp in your terminal and restart Claude Code.
What does OpenOCD Debugger do?
It provides tools for an agent to flash microcontrollers, control chip execution, set breakpoints, and inspect memory or registers.
What is required to run OpenOCD Debugger?
You need Python 3.10+, a hardware probe like ST-Link or J-Link, and a target board. The server downloads OpenOCD binaries automatically if OPENOCD_BIN is unset.