Skip to main content
Glama

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_PATH

OpenOCD 可执行文件路径

openocd

GDB_PATH

GDB 可执行文件路径

arm-none-eabi-gdb

OPENOCD_SCRIPTS

OpenOCD 脚本搜索路径

""

RTT_PORT

RTT 服务器端口

8888

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 工具列表

项目与配置

工具

描述

set_project(project_dir)

加载项目 .vscode/launch.json,解析所有调试配置

refresh_debug_targets()

重新加载 launch.json 配置(修改后刷新)

get_runtime_config()

查看当前 OpenOCD/GDB 路径及其来源

烧录与调试

工具

描述

flash_download(config_name, firmware_path?)

一次性烧录固件(不启动调试会话)

debug_start(config_name, firmware_path?)

启动 OpenOCD + GDB 调试会话,加载固件,可选运行到入口点

debug_attach(config_name, firmware_path?)

附加到运行中的目标,不下载固件、不复位(Attach 模式)

debug_stop()

终止当前调试会话

debug_command(command)

执行任意 GDB 命令

debug_continue()

继续目标执行(异步,立即返回)

debug_interrupt()

中断/暂停运行中的目标

状态与日志

工具

描述

debug_status()

获取调试会话状态(JSON)

debug_state()

获取目标执行状态和停止原因

read_rtt(max_lines)

读取 RTT 实时日志(默认 10 行)

shutdown()

优雅关闭 MCP 服务器

架构

AI 客户端 → MCP 协议 → openocd-mcp
                           ├── ProjectConfigManager (解析 launch.json)
                           ├── OpenOCDController (启动/停止 OpenOCD 进程)
                           ├── GDBMISession (MI2 异步协议通信)
                           ├── RTTClient (实时日志读取)
                           └── DebugSessionManager (协调生命周期)

模块

职责

ProjectConfigManager

解析 .vscode/launch.json,替换 ${workspaceFolder},缓存配置

OpenOCDController

启动 OpenOCD 进行烧录(program)或作为 GDB 服务器(:3333)

GDBMISession

GDB/MI 异步会话,协议解析、事件驱动、无需轮询提示符

RTTClient

TCP 连接 RTT 端口,后台线程按行缓冲读取日志

DebugSessionManager

单会话模型,协调 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 halt

  • RTT 非致命:固件不支持 RTT 时,调试会话照常运行,RTT 功能不可用但不影响其他操作

  • 超时控制:普通 GDB 命令 30 秒超时,load 120 秒,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 tools
debug_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

    A3.8/5.0

    Scored across 8 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      An 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.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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 npm
      4
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Stateful 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.
      41
      87 PyPI
      11
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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.
      2
      MIT