OpenOCD MCU MCP

OpenOCD MCU MCP gives coding agents a practical bridge into real MCU debug sessions. It combines a stdio MCP server, a small OpenOCD telnet CLI, CMSIS-SVD register decoding, and a Codex skill for Cortex-M and RISC-V diagnosis workflows.

It is designed for hardware bring-up and fault investigation: identify the connected chip, halt/resume/reset through OpenOCD, inspect CPU registers, read target memory, find SVD files, decode peripheral registers, and route common failures such as HardFaults, hangs, clock issues, peripheral misconfiguration, and memory corruption.

Why this project

• OpenOCD backend, so it works with OpenOCD-supported probes such as CMSIS-DAP, ST-Link, J-Link, and custom adapters.
• No third-party Python runtime dependencies.
• Installable CLI and stdio MCP server.
• CMSIS-SVD lookup, optional download, and bitfield-level register decoding.
• Real-hardware smoke tested with STM32F407 + CMSIS-DAP over SWD.
• Includes a Codex skill with diagnosis playbooks for MCU debugging.

Install

From a checkout:

python -m pip install -e .

After installation, these commands are available:

openocd-mcu
openocd-mcu-mcp
openocd-mcu-probe
openocd-mcu-find-svd
openocd-mcu-fetch-svd
openocd-mcu-decode-register
openocd-mcu-elf

60-second STM32F407 demo

Start OpenOCD for a CMSIS-DAP probe and STM32F4 target:

openocd-mcu start `
  --interface interface/cmsis-dap.cfg `
  --target target/stm32f4x.cfg `
  --adapter-speed 4000

Check the connection and identify the chip:

openocd-mcu connect
openocd-mcu-probe --halt

Fetch an SVD file, read RCC_CR, and decode the bitfields:

openocd-mcu-fetch-svd STM32F407 --download .\openocd-mcu-debug\svd\arm\STMicro
openocd-mcu mdw 0x40023800 1 --json
openocd-mcu-decode-register `
  --svd .\openocd-mcu-debug\svd\arm\STMicro\STM32F407.svd `
  --peripheral RCC `
  --register CR `
  --value 0x00007E83

Expected hardware evidence from the smoke test:

CPUID = 0x410FC241
Core = Cortex-M4
DBGMCU_IDCODE = 0x100F6413
DEV_ID = 0x413
Family hint = STM32F405/407/415/417
RCC_CR @ 0x40023800 = 0x00007E83

See examples/stm32f407-cmsis-dap-smoke-test.md for the full run.

MCP server

Run the stdio MCP server:

openocd-mcu-mcp

Example MCP client config:

{
  "mcpServers": {
    "openocd-mcu": {
      "command": "openocd-mcu-mcp"
    }
  }
}

Available MCP tools:

• connect
• halt
• resume
• reset_halt
• register_read
• registers
• memory_read
• memory_write
• raw_command
• probe_chip
• find_svd
• decode_register

MCP tools execute the requested debug operation directly. Use them only against targets where changing run state or memory is acceptable. The manual CLI keeps confirmation switches for dangerous operations such as writes, reset, flash commands, and resume.

Codex skill

Install the skill by copying openocd-mcu-debug/ into your Codex skills directory:

Copy-Item -Recurse .\openocd-mcu-debug "$env:USERPROFILE\.codex\skills\openocd-mcu-debug"

Then invoke:

Use $openocd-mcu-debug to identify the connected STM32 and decode RCC_CR.

openocd-mcu-debug/
├── SKILL.md
├── openocd-debugging-workflow.md
├── chip-probing-workflow.md
├── register-decoding.md
├── chip-id-reference.md
├── elf-debugging-workflow.md
├── hardfault-diagnosis.md
├── hang-diagnosis.md
├── peripheral-diagnosis.md
├── clock-diagnosis.md
└── memory-diagnosis.md

Compatibility

| Area | Current status | |---|---| | Host OS | Windows + PowerShell smoke tested | | OpenOCD | 0.12.0 smoke tested | | Probe | CMSIS-DAP smoke tested; ST-Link/J-Link expected through OpenOCD configs | | Target | STM32F407 real-hardware smoke tested | | Architecture | Cortex-M path implemented; RISC-V CSR probing path included | | SVD data | Not bundled; downloaded on demand from upstream sources |

Safety model

The CLI defaults to read-oriented commands. These operations require explicit confirmation flags:

| Operation | CLI guard | |---|---| | RAM/peripheral write | --confirm-write | | Raw dangerous command | --allow-dangerous | | Resume or step | --allow-run | | Reset halt | --confirm-reset |

The MCP server intentionally exposes direct tools for agent workflows, so client-side prompting and user intent matter.

Development

python -m pip install -e .
python -m unittest discover -v
python -m compileall openocd_mcu_mcp openocd-mcu-debug\scripts openocd-mcu-debug\tools

License

Code and original documentation are released under the MIT License. CMSIS-SVD files are not bundled by default; use openocd-mcu-fetch-svd or fetch_svd.py to download them from upstream sources and respect upstream license notices.