# OpenOCD Debugger

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5 repo stars
- Author: microhenrio
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/microhenrio/openocd-mcp
- Updated: 2026-07-02
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/openocd-debugger

## What it 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`.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `OPENOCD_BIN`, `OPENOCD_MCP_CONFIG`, `OPENOCD_MCP_READONLY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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-mcp
```
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>

### Codex

**Platform CLI**
```bash
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-mcp
```
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>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
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-mcp
```
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>

## When to use it
- flash firmware images in `.elf`, `.bin`, or `.hex` format
- 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
- Flash `build/app.bin` to the connected board and issue a reset
- Add a conditional breakpoint on `rx_buffer_overflow` and halt on hit
- Read the bitfields of `RCC.CR` according to our chip SVD file

## Similar
- [openocd-jtag](https://affpapa.org/en/nevibecode/skills/openocd-jtag.md) — skill · 637 installs
- [embedded-systems](https://affpapa.org/en/nevibecode/agents/voltagent-embedded-systems.md) — subagent · ★ 6505 repo stars
- [domain-embedded](https://affpapa.org/en/nevibecode/skills/domain-embedded.md) — skill · 3200 installs
- [McuBuddy](https://affpapa.org/en/nevibecode/mcp/mcubuddy.md) — MCP server · ★ 12 repo stars
- [freertos](https://affpapa.org/en/nevibecode/skills/freertos.md) — skill · 739 installs
- [lgt8f328p-minievb](https://affpapa.org/en/nevibecode/skills/lgt8f328p-minievb.md) — skill · ★ 29 repo stars

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
