openocd-mcp
The openocd-mcp server provides an AI-callable interface for embedded firmware flashing and GDB debugging via OpenOCD, reusing existing .vscode/launch.json configurations with no extra setup required.
Project & Configuration Management: Set the project directory to load and parse
.vscode/launch.jsondebug targets; refresh targets after changes; view the currently effective OpenOCD/GDB runtime configuration and its sources.Flashing: Download firmware to a target microcontroller using a specified launch configuration without starting a full debug session.
Debugging: Start a debug session (launch OpenOCD + GDB, load firmware, optionally halt at entry point); attach to a running target without downloading firmware or resetting; stop the active session, terminating OpenOCD and GDB processes; execute arbitrary GDB commands; continue execution asynchronously; interrupt/pause the running target.
Status & Logging: Retrieve current debug session status and available configuration names (JSON); query target execution state and stop reason; read real-time RTT logs from the MCU.
Lifecycle: Gracefully shut down the MCP server.
Supports stdio (VS Code MCP) and SSE/HTTP modes across Windows, Linux, and macOS.
Provides tools for debugging and flashing firmware on Arm-based microcontrollers by integrating with OpenOCD and GDB, allowing for project management and real-time status monitoring.
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., "@openocd-mcp flash the firmware using the STM32 configuration"
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
基于 fastmcp 的 OpenOCD 调试 MCP 服务器,将嵌入式烧录与 GDB 调试工作流封装为 AI 可调用的工具。复用项目已有的 .vscode/launch.json 作为调试目标来源,无需额外配置。
特性
🔧 零配置 — 直接复用 VS Code 的
launch.json,无需维护额外配置文件⚡ GDB/MI 异步协议 — 基于 MI2 事件驱动,
continue不阻塞,interrupt即时生效📡 RTT 实时日志 — 自动连接 SEGGER RTT,读取 MCU 运行时输出
🖥️ 跨平台 — 支持 Windows / Linux / macOS,Windows 上自动回退 OpenOCD telnet halt
🔄 双模式运行 — stdio(VS Code MCP)和 SSE/HTTP(本地 AI 客户端)
Related MCP server: commands-mcp
快速开始
安装
# 克隆仓库
git clone https://github.com/luiox/openocd-mcp.git
cd openocd-mcp
# 安装依赖
uv sync运行
# stdio 模式(VS Code MCP 默认)
uv run openocd-mcp
# 自定义工具路径
uv run openocd-mcp --openocd-path /usr/bin/openocd --gdb-path /usr/bin/arm-none-eabi-gdb
# SSE/HTTP 模式(给本地其他 AI 客户端)
uv run openocd-mcp -sse --host 127.0.0.1 --port 9000参数优先级:命令行参数 > 环境变量 > config.json > 内置默认值。
环境变量
变量 | 说明 | 默认值 |
| OpenOCD 可执行文件路径 |
|
| GDB 可执行文件路径 |
|
| OpenOCD 脚本搜索路径 |
|
| RTT 服务器端口 |
|
config.json 配置
在项目根目录创建 config.json(已被 .gitignore 忽略):
{
"openocd_path": "D:/sdk/OpenOCD/bin/openocd.exe",
"gdb_path": "D:/sdk/Arm GNU Toolchain/bin/arm-none-eabi-gdb.exe",
"openocd_scripts": "D:/sdk/OpenOCD/share/openocd/scripts",
"rtt_port": 8888,
"adapter_speed": 0
}VS Code 集成
项目已包含 .vscode/mcp.json,使用 stdio 模式启动:
{
"servers": {
"openocd-mcp": {
"type": "stdio",
"command": "uv",
"args": ["run", "openocd-mcp"],
"cwd": "${workspaceFolder}"
}
}
}如需 SSE 模式:
{
"servers": {
"openocd-mcp": {
"type": "sse",
"url": "http://127.0.0.1:9000/sse"
}
}
}MCP 工具列表
项目与配置
工具 | 描述 |
| 加载项目 |
| 重新加载 launch.json 配置(修改后刷新) |
| 查看当前 OpenOCD/GDB 路径及其来源 |
烧录与调试
工具 | 描述 |
| 一次性烧录固件(不启动调试会话) |
| 启动 OpenOCD + GDB 调试会话,加载固件,可选运行到入口点 |
| 附加到运行中的目标,不下载固件、不复位(Attach 模式) |
| 终止当前调试会话 |
| 执行任意 GDB 命令 |
| 继续目标执行(异步,立即返回) |
| 中断/暂停运行中的目标 |
状态与日志
工具 | 描述 |
| 获取调试会话状态(JSON) |
| 获取目标执行状态和停止原因 |
| 读取 RTT 实时日志(默认 10 行) |
| 优雅关闭 MCP 服务器 |
架构
AI 客户端 → MCP 协议 → openocd-mcp
├── ProjectConfigManager (解析 launch.json)
├── OpenOCDController (启动/停止 OpenOCD 进程)
├── GDBMISession (MI2 异步协议通信)
├── RTTClient (实时日志读取)
└── DebugSessionManager (协调生命周期)模块 | 职责 |
| 解析 |
| 启动 OpenOCD 进行烧录( |
| GDB/MI 异步会话,协议解析、事件驱动、无需轮询提示符 |
| TCP 连接 RTT 端口,后台线程按行缓冲读取日志 |
| 单会话模型,协调 OpenOCD + GDB + RTT 生命周期 |
launch.json 要求
目标项目必须包含 .vscode/launch.json,每个配置需包含:
name— 配置名称(唯一标识)configFiles— OpenOCD 脚本列表(如["interface/cmsis-dap.cfg", "target/stm32f1x.cfg"])executable— 固件 ELF 文件路径(支持${workspaceFolder}变量)runToEntryPoint(可选)— 入口点断点(如"main")
示例:
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug STM32",
"type": "cortex-debug",
"request": "launch",
"configFiles": [
"interface/cmsis-dap.cfg",
"target/stm32f1x.cfg"
],
"executable": "${workspaceFolder}/build/firmware.elf",
"runToEntryPoint": "main"
}
]
}支持 JSON 中的 C 风格注释和尾随逗号(自定义解析器自动清理)。
关键设计
单会话模型:同时最多一个调试会话,
debug_start自动停止之前的会话异步继续:
debug_continue()通过 MI^running立即返回,不阻塞等待目标停止中断机制:优先使用 GDB/MI
-exec-interrupt;Windows 上自动回退到 OpenOCD telnet haltRTT 非致命:固件不支持 RTT 时,调试会话照常运行,RTT 功能不可用但不影响其他操作
超时控制:普通 GDB 命令 30 秒超时,
load120 秒,flash 180 秒路径处理:Windows 路径自动转换为正斜杠(OpenOCD 兼容)
项目结构
openocd_mcp/
├── __init__.py # 包入口
├── __main__.py # python -m 入口
├── server.py # MCP 工具定义 + main() 入口
├── config.py # GlobalConfig, ProjectConfigManager
├── openocd.py # OpenOCDController
├── gdb_mi.py # GDBMISession (MI2 异步协议)
├── rtt.py # RTTClient (TCP 日志读取)
└── session.py # DebugSessionManager文档
License
MIT
Available Tools
8 toolsdebug_commandC
Execute one GDB command in current active debug session.
Inputs: command (required). Returns: result
debug_startC
Start debug session using specified launch configuration.
Inputs: config_name (required), firmware_path. Returns: result
debug_statusA
Get current debug session status and available configuration names in JSON string format.
Inputs: no named parameters. Returns: result
debug_stopA
Stop current active debug session and terminate OpenOCD/GDB processes.
Inputs: no named parameters. Returns: result
flash_downloadB
Flash firmware once using specified launch configuration without starting debug session.
Inputs: config_name (required), firmware_path. Returns: result
get_runtime_configA
Return currently effective OpenOCD/GDB runtime configuration and value sources for troubleshooting.
Inputs: no named parameters. Returns: result
refresh_debug_targetsA
Reload launch.json from current project and return available debug configurations.
Inputs: no named parameters. Returns: result
set_projectB
Set current project directory and load debug configurations from .vscode/launch.json.
Inputs: project_dir (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 8 tools
Each tool has a clearly distinct purpose with no ambiguity: debug_start initiates a session, debug_stop terminates it, debug_command executes a command, debug_status checks status, flash_download flashes firmware, get_runtime_config retrieves configuration, refresh_debug_targets reloads targets, and set_project sets the project directory. The tools cover different aspects of debugging and flashing workflows without overlap.
All tool names follow a consistent verb_noun pattern (e.g., debug_start, debug_status, flash_download, get_runtime_config) using snake_case throughout. This predictability makes it easy for agents to understand and select the appropriate tool based on its name.
With 8 tools, the server is well-scoped for its purpose of debugging and flashing firmware via OpenOCD/GDB. Each tool earns its place by covering essential operations like starting/stopping sessions, executing commands, checking status, flashing, and managing configurations, without being overly sparse or bloated.
The tool set provides complete coverage for the debugging and flashing domain: it supports session lifecycle (start, stop, status), command execution, firmware flashing, configuration management (get, refresh, set), and project setup. There are no obvious gaps, enabling agents to handle typical workflows without dead ends.
Related MCP Connectors
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.
The MCP server for Azure DevOps, bringing the power of Azure DevOps directly to your agents.
Repository knowledge graph MCP server for codebase understanding and debugging.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceAn MCP server and VS Code extension that enables AI clients to interactively debug code using breakpoints, execution control, and state inspection. It is language-agnostic and works with any debugger that supports VS Code's launch.json configurations.-
- AlicenseNot gradedqualityDmaintenanceAn MCP server that lets you define and run custom shell commands via YAML templates, with built-in tools for flashing and serial communication in embedded development.10 npm4Apache 2.0
- 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.4187 PyPI11MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for embedded debugging based on probe-rs, providing 22 tools for ARM Cortex-M and RISC-V microcontrollers, including connection, memory operations, breakpoints, flash programming, and RTT communication.2MIT