Skip to main content
Glama
keil-mdk-mcp

keil-mdk-mcp

by lideshengstu

keil-mdk-mcp

Tests Python License: MIT MCP

English: An MCP (Model Context Protocol) server that lets AI agents build, flash and debug STM32 projects compiled with Keil MDK-ARM on Windows. Build/flash run the official UV4.exe command line; debugging uses a separate pyOCD/ST-Link backend. Every result is evidence-based — this project explicitly refuses to fake unverified capabilities.

状态声明(请务必阅读):这是一个可运行但范围受限的交付版本。 已真实验证:MCP stdio 接入、29 个工具、Keil 完整/增量编译、编译日志解析、真实 .axf 的 ELF/DWARF 符号解析、ST-Link USB 枚举、安全拒绝路径。 未做硬件验收:烧录、MCU 连接/复位、断点命中、实时变量/寄存器读取均未在真实板子上验证。 未实现且不会假装实现:原生 µVision UVSOCK/DDE 控制、源码级单步(into/over/out)、调用栈回溯、局部变量与任意 C 表达式求值。相关工具返回明确的 E_NOT_IMPLEMENTED / 未验证错误,绝不返回伪造的成功。

详细能力边界见 docs/capability_matrix.md,官方接口调研记录见 docs/official_interfaces.md。

它解决什么问题

AI Agent 写嵌入式代码时缺的不是语法,而是执行反馈:不知道 Keil 报错在哪一行,不知道固件是否真的在板子上跑起来。本服务把这条反馈链封装成 MCP 工具:

  • 用官方 UV4 -b/-r 编译工程,返回结构化的错误/警告(文件、行号、列号)

  • 编译成功判定采用三重证据:进程退出码(官方 ERRORLEVEL 表)+ 日志权威汇总行 + 预期产物文件存在且非空(重编译还要求产物指纹变化)——不是搜索日志里有没有 "Error" 字符串

  • 通过 pyOCD 直接连接 ST-Link,提供运行控制、硬件断点、寄存器/PC 读取、全局/静态变量读取(从 DWARF 符号定位地址后实时读取目标内存,运行中拒绝读取,绝不用缓存值冒充)

  • 所有硬件操作有明确的确认门和串行化保护

Related MCP server: Keil5 MCP Server

与调试后端的重要说明

调试走 pyOCD 直接连接 ST-Link(Arm 官方开源调试器),这是独立调试器,不是控制正在运行的 µVision 调试窗口。两者不能同时占用同一个探针。调研结论:µVision 存在官方 UVSOCK 远程接口,但其 SDK/线协议未能在本次开发中取得可验证的文档正文,因此本服务诚实地不实现它(stub 永远返回未实现错误),留作后续方向。

环境要求

组件

要求

OS

Windows 10/11

Python

3.11+(实测 3.13)

Keil MDK

µVision 5(UV4.exe,实测 5.24),ARMCC 或 ARMCLANG

调试器

ST-Link(pyOCD 支持 CMSIS-DAP/J-Link 等,未逐一实测)

MCP 客户端

任何支持 stdio MCP 的客户端(Workbuddy / Claude Desktop / Cursor 等,客户端 UI 未逐一实测)

安装

推荐虚拟环境(不污染全局 Python):

git clone https://github.com/<YOUR_USERNAME>/keil-mdk-mcp.git
cd keil-mdk-mcp
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install ".[debug,dev]"

只使用编译/日志功能(不调试)可以省略 pyOCD:

.\.venv\Scripts\python.exe -m pip install .

离线自测:

.\.venv\Scripts\python.exe -m pytest -q

MCP 客户端配置(stdio)

以 Workbuddy / Claude Desktop 等支持 mcpServers JSON 的客户端为例,见 config/workbuddy.mcp.example.json:

{
  "mcpServers": {
    "keil": {
      "command": "C:\\absolute\\path\\to\\.venv\\Scripts\\python.exe",
      "args": ["C:\\absolute\\path\\to\\keil-mdk-mcp\\run_server.py"],
      "env": {
        "PYTHONUTF8": "1",
        "KEIL_UV4_PATH": "D:\\Keil_v5\\UV4\\UV4.exe",
        "KEIL_DEFAULT_PROJECT": "D:\\path\\to\\your\\project\\MDK-ARM\\app.uvprojx",
        "KEIL_ALLOWED_ROOTS": "D:\\path\\to\\your\\project",
        "KEIL_ALLOW_FLASH": "false"
      }
    }
  }
}

关键环境变量:

变量

说明

KEIL_UV4_PATH

UV4.exe 绝对路径(不设则自动探测常见安装位置)

KEIL_DEFAULT_PROJECT

默认 .uvprojx,设置后其所在目录自动加入路径白名单

KEIL_ALLOWED_ROOTS

路径白名单(分号分隔多个),覆盖工程与编译产物目录;未配置且无默认工程时拒绝读文件

KEIL_ALLOW_FLASH

烧录总开关,默认 false;开启后仍需 confirm=true

KEIL_ARTIFACTS_DIR

编译日志、会话 JSONL 的输出目录(默认 <repo>/artifacts)

KEIL_DEBUG_BACKEND

调试后端,目前仅 pyocd

快速上手(接入后第一轮)

  1. keil_get_environment —— 检查 UV4 / Python 包 / 安全配置

  2. keil_get_project_info —— 解析 Target、器件、编译器、输出配置

  3. keil_build / keil_rebuild —— 编译,返回退出码 + 结构化诊断 + 产物指纹

  4. keil_get_build_log / keil_parse_build_errors —— 查看日志与错误定位

  5. keil_diagnose_connection —— 枚举 ST-Link(只枚举 USB,不连接 MCU)

工具清单(29 个)

环境/工程:keil_get_environment keil_get_project_info keil_get_status 编译/日志:keil_build keil_rebuild keil_get_build_log keil_parse_build_errors 下载/会话:keil_flash keil_start_debug keil_stop_debug keil_run keil_halt keil_reset 断点:keil_set_breakpoint keil_remove_breakpoint keil_list_breakpoints 单步:keil_step_instruction(指令级);keil_step_into/over/out 未实现,明确返回错误 观察:keil_read_variable keil_read_variables keil_get_registers keil_get_pc keil_get_execution_state;keil_get_call_stack 未实现 诊断:keil_get_last_error keil_get_session_log keil_diagnose_connection

每个工具的参数、默认值、返回 JSON 示例与错误码见 docs/tools.md 与 artifacts 之外的 schema 说明。

安全模型

  • 烧录/连接调试器/复位需要宿主配置开启(KEIL_ALLOW_FLASH=true)且调用时带 confirm=true——两者缺一不可。confirm=true 是结构化门槛,请同时在你的 MCP 客户端保留人工审批。

  • 路径白名单 + 绝对路径校验,阻止相对路径穿越;解析后按真实路径校验。

  • 所有子进程调用使用参数数组(shell=False),拒绝执行工程里已启用的 User Program 自定义命令(E_UNSAFE_PROJECT)。

  • 全部编译/烧录/调试操作共用单 worker + 串行锁:并发请求返回 E_BUSY,超时操作不释放所有权(E_SESSION_FAULTED 直到 worker 结束并断开会话),不会出现两个工具同时操作目标。

  • 每个探针只能有一个服务实例;没有跨进程探针锁,不要与打开的 µVision 或其他调试软件同时占用 ST-Link。

  • pyOCD 侧禁用自动解锁(保护芯片不被意外擦除)、断开后自动恢复运行、内存/寄存器缓存、自动加载项目目录下的用户脚本与配置。

返回格式

所有工具返回 MCP structuredContent JSON:

{"ok": true, "error_code": "OK", "data": {"status": "success", "exit_code": 0}}
{"ok": false, "error_code": "E_CONFIRMATION_REQUIRED",
 "error": "flash overwrites MCU memory; obtain human authorization and reissue with confirm=true", "data": {}}

完整错误码表见 docs/tools.md。

架构

run_server.py            绝对路径启动入口(stdio)
src/keil_mcp/
  server.py              MCP 工具定义 / 参数 schema / structured output
  keil_adapter.py        UV4 官方命令行封装 / 超时与进程树清理 / 证据判定
  session_manager.py     单 worker 串行事务 / 超时隔离 / JSONL 操作日志
  safety.py              路径白名单 / 文件类型 / 硬件确认门
  config.py              环境变量与默认值
  result.py              统一 JSON 结果结构
  parsers/               编译日志(ARMCC/ARMCLANG) / 工程XML / ELF-DWARF 符号与行表
  debug_backends/        pyOCD 后端 / UVSOCK 明确未实现 stub

已验证 / 未验证(诚实清单)

能力

状态

MCP stdio、29 工具注册、structured output

真实验证

Keil -b / -r 编译 + 日志解析(0 错误 0 警告 + 产物)

真实验证(STM32F103C8 工程)

真实 .axf 的 ELF/DWARF 符号、行表、函数解析

真实验证

ST-Link USB 枚举

真实验证

烧录 UV4 -f

实现未验(默认关闭;缺擦除/编程/校验日志证据时返回未验证错误)

pyOCD 会话/运行控制/断点/寄存器/变量

实现未验(41 项测试含 mock 回归;需板级验收)

UVSOCK/DDE、源码级单步、调用栈、局部变量

未实现,明确报错

测试细节见 docs/test_report.md。

License

MIT。本仓库仅包含项目源码与文档;Keil、pyOCD、CMSIS 等第三方组件各自遵循其许可。

Available Tools

29 tools
keil_buildC

UV4 -b incremental build. Requires exit code, summary and expected nonempty output evidence.

Inputs: target, project_path. Returns: object

keil_diagnose_connectionA

Enumerate probes without connecting/resetting; USB presence does not prove target power or SWD connectivity.

Inputs: no named parameters. Returns: object

keil_flashB

UV4 -f download; requires host KEIL_ALLOW_FLASH=true and human-authorized confirm=true. Not hardware-tested.

Inputs: target, confirm, project_path. Returns: object

keil_get_build_logA

Read global latest log or a basename from server artifacts/build-logs (1..5000 lines). project_path is optional compatibility metadata, not a filter.

Inputs: log_name, tail_lines, project_path. Returns: object

keil_get_call_stackC

Validated stack unwinding is not implemented; no guessed frames are returned.

Inputs: no named parameters. Returns: object

keil_get_environmentB

Report UV4 path/version, package versions, path policy and hardware safety gates.

Inputs: no named parameters. Returns: object

keil_get_execution_stateA

Observe CPU state, halt reason, exception number and confirmed breakpoint hit when available.

Inputs: no named parameters. Returns: object

keil_get_last_errorA

Return the latest recorded operation error without touching target hardware.

Inputs: no named parameters. Returns: object

keil_get_pcA

Read the actual program counter from a halted target.

Inputs: no named parameters. Returns: object

keil_get_project_infoB

Parse targets/device/compiler/output settings; project_path must be allowlisted.

Inputs: project_path. Returns: object

keil_get_registersB

Read fresh Cortex-M core registers while halted; reject unsupported names.

Inputs: registers. Returns: object

keil_get_session_logB

Return the most recent 1..500 operation records and durable JSONL log path.

Inputs: tail. Returns: object

keil_get_statusB

Server session/worker status; does not claim to observe CPU state.

Inputs: no named parameters. Returns: object

keil_haltA

Request halt and verify the target reports HALTED.

Inputs: no named parameters. Returns: object

keil_list_breakpointsB

List confirmed breakpoints belonging to this backend session.

Inputs: no named parameters. Returns: object

keil_parse_build_errorsC

Parse errors/warnings and file/line from latest artifact log or named basename.

Inputs: log_name, project_path. Returns: object

keil_read_variableA

Read a fresh, unambiguous global/static base-type variable while halted. Locals and expressions are unsupported.

Inputs: name (required). Returns: object

keil_read_variablesA

Read 1..64 variables in one serialized transaction; per-variable errors are preserved.

Inputs: names (required). Returns: object

keil_rebuildC

UV4 -r full rebuild; require fresh expected output in addition to log/exit evidence.

Inputs: target, project_path. Returns: object

keil_remove_breakpointB

Remove and verify removal of a breakpoint at a hex or decimal address.

Inputs: address (required). Returns: object

keil_resetA

Reset MCU only after human-authorized confirm=true; optionally halt afterward.

Inputs: confirm, halt_after. Returns: object

keil_runA

Resume target; report observed state separately from request submission.

Inputs: no named parameters. Returns: object

keil_set_breakpointB

Set a hardware breakpoint by unique source file/line or 32-bit address. Request, confirmation and hit are distinct.

Inputs: file, line, address. Returns: object

keil_start_debugA

Connect pyOCD/ST-Link (NOT native µVision). May halt MCU, so requires human-authorized confirm=true. target_override is required; ELF defaults to the selected project's output.

Inputs: target, backend, confirm, elf_path, +3 more. Returns: object

keil_step_instructionA

Execute exactly one machine instruction on a halted target; not a source-level step.

Inputs: no named parameters. Returns: object

keil_step_intoB

Source-level step into is not implemented; never substitute instruction stepping.

Inputs: timeout_s. Returns: object

keil_step_outC

Function step out is not implemented without validated unwind information.

Inputs: timeout_s. Returns: object

keil_step_overA

Source-level step over is not implemented; returns an explicit unsupported result.

Inputs: timeout_s. Returns: object

keil_stop_debugA

Disconnect and release the probe without automatically resuming the MCU.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 29 tools

    Disambiguation3/5

    Most tools map to a distinct resource+action, but there are near-duplicate pairs: keil_read_variable vs keil_read_variables (singular vs batch) and keil_get_status vs keil_get_execution_state vs keil_get_pc, which an agent could easily misselect. The three source-level step tools (step_into/step_over/step_out) all return 'unsupported' and overlap functionally with keil_step_instruction, adding noise rather than clarity.

    Naming Consistency4/5

    All 29 tools use a consistent keil_ prefix plus verb_noun form (get_*, read_*, set_*, step_*, build/rebuild/flash), which is highly predictable. The only blemish is the singular/plural pair keil_read_variable / keil_read_variables, where the names differ by one character but describe different scopes.

    Tool Count2/5

    At 29 tools the surface is heavy for a single debug/build server, and several slots are effectively placeholders: keil_step_into, keil_step_over, keil_step_out and keil_get_call_stack exist only to report 'not implemented'. Trimming those and folding status/execution-state queries together would bring it into a reasonable scope.

    Completeness3/5

    Core lifecycle is covered: project info, build/rebuild/logs/error parsing, flash, connect/disconnect, reset/run/halt, breakpoint CRUD, register/variable reads, and diagnostics. However, source-level stepping and call-stack unwinding are explicitly absent, and there is no memory or register write, no expression/watch evaluation, and no peripheral access, leaving common debug workflows with dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI tools to perform full-featured embedded microcontroller debugging via pyOCD and CMSIS-DAP probes, including probe management, flashing, breakpoints, register/memory access, fault analysis, and RTT communication.
      58
      2
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      Enables AI coding agents to build, flash, debug, and read feedback from STM32 development projects in Keil MDK, forming a closed loop to automatically fix code.
      27
      15
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to compile, debug, sample, and inspect MCU firmware through J-Link/pyOCD or a mock engine, including breakpoints, watchpoints, single-stepping, register access, and flash dump operations.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to debug STM32 firmware on real hardware by driving GDB with OpenOCD/ST-Link/J-Link to flash, set breakpoints, inspect memory, registers and RTOS state, triage HardFaults, and profile. Returns decoded, structured evidence and suggested next actions instead of raw GDB text, with composite tools that collapse multi-step debug loops into single calls.
      86
      4
      MIT