keil-uvsc-mcp

让 AI 通过 MCP 协议直接驱动 Keil µVision 调试 8051/C51 单片机。 An MCP server that lets AI assistants drive Keil µVision (via the UVSOCK/UVSC interface) to debug 8051/C51 targets.

中文 · English

中文

AI 编程助手（Claude Code / Claude Desktop / Kimi 等 MCP 客户端）连接本服务器后，可以在 Keil 调试会话中：编译工程、进入/退出 Debug、运行控制（run/stop/reset/单步）、设断点、读变量/内存/表达式、写内存——全程不用切回 Keil 界面。

共 22 个 MCP 工具，单文件 EXE，零第三方依赖，开箱即用。

⚠️ 本项目与 Arm / Keil 官方无关，仅为基于 µVision 公开 UVSOCK/UVSC 接口的个人开源工具。

为什么做这个

8051/C51 没有 pyOCD / OpenOCD 那样的开源调试生态，Keil 是事实标准，但 Keil 没有 AI 接口。本工具通过 µVision 原生的 UVSOCK socket + UVSC DLL 接口 attach 到调试会话，把 Keil 的调试能力以标准 MCP 协议暴露给 AI。支持 纯 Simulator 仿真（无需硬件），也支持 GLink+ / ULINK 等在线调试器。

与同类项目对比

快速开始

前置条件：Windows + Keil µVision v5（UV4\UVSC64.dll 存在）；.NET Framework 4.x（Win10/11 自带）。

1. 开启 UVSOCK（一次性，必须走 GUI）：µVision → Edit → Configuration → Other → UVSOCK 勾选 Enable，端口 4823。

2. 注册 MCP（以 Claude Code 为例）：

   claude mcp add keil-uvsc "<解压目录>\bin\KeilUvscMcp.exe"

   Claude Desktop 配置模板见 mcp-config/。

3. 每次调试会话的顺序：µVision 打开工程 → 进 Debug（Ctrl+F5，Simulator 无需硬件）→ AI 侧 keil_connect(mode=attach, port=4823)。

然后就可以对 AI 说：「编译一下」「在 main 下断点跑起来」「读 g_tick 的值」。

工具清单（22 个）

无烧录功能（UVSOCK 不提供）。烧录请搭配 stcgal / stc8prog 等 ISP 工具。

验证

verify/ 下有 10 个 Python 冒烟脚本，JSON-RPC over stdio 直连 EXE，不依赖任何 MCP 客户端：

cd verify
python verify_read.py     # 读变量（需 Keil 已在 Debug）
python verify_bp.py       # 断点
python verify_runctl.py   # 运行控制
python verify_build.py    # 编译

实测踩坑（别处看不到的）

• 8051 地址编码 0xSSSS_AAAA：高 16 位是空间选择（CODE=0xFF00、XDATA=0x0100），裸地址默认落 CODE 空间。稳妥做法：先 keil_eval_expression &变量名 拿带前缀的地址再读写。

• GLink+ 同时只能存在 1 个断点，下新断点前必须先清旧的，否则 UVSC 超时卡死整个 µVision。

• GLink+ 运行中不能读变量/设断点，须先 halt。

• keil_exit_debug 会崩掉 UV4 进程——要重编译请直接关掉 µVision 以编辑模式重开。

完整记录见 docs/验证记录.md 与 部署指南.md。

实战案例

QI 无线充电工程「断开错误码」抓取：在错误处理唯一汇聚点下单断点 → AI 轮询 keil_get_status 等命中 → 读错误码与 EPT 包解析断开原因。详见 部署指南.md 第 8 节。

重编译

C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe /nologo /platform:x64 /out:bin\KeilUvscMcp.exe src\Program.cs

目录

bin/KeilUvscMcp.exe   MCP 服务器（.NET Framework x64 单文件）
src/Program.cs        全部源码（单文件）
src/UVSC_C.h UVSOCK.h Keil UVSC/UVSOCK 协议头文件（参考）
mcp-config/           Claude Code / Claude Desktop 注册模板
verify/               10 个冒烟验证脚本
docs/                 调研报告 / 实现方案 / SOP / 验证记录
DemoC51/              C51 演示工程（Simulator 冒烟目标）

License

MIT

Related MCP server: dbgprobe-mcp-server

English

An MCP (Model Context Protocol) server that attaches to a live Keil µVision debug session through the native UVSOCK socket + UVSC DLL interface and exposes it to AI assistants (Claude Code, Claude Desktop, Kimi, any MCP client) as 22 structured tools: build the project, enter/exit debug, run control (run/halt/reset/step), breakpoints, and read/write variables, expressions and target memory — focused on 8051/C51 targets, with support for both the Keil Simulator (no hardware needed) and in-circuit debuggers such as GLink+ / ULINK.

⚠️ Not affiliated with Arm / Keil. Built on the documented UVSOCK/UVSC interface of µVision.

Quick start

1. Enable UVSOCK once in µVision: Edit → Configuration → Other → UVSOCK → Enable, port 4823.

2. Register the server, e.g. for Claude Code:

   claude mcp add keil-uvsc "<install-dir>\bin\KeilUvscMcp.exe"

   Templates for Claude Desktop live in mcp-config/.

3. Session order matters: open the project in µVision → enter Debug (Ctrl+F5) → then call keil_connect(mode=attach, port=4823) from the AI side.

No flashing support (UVSOCK does not expose it) — pair with an ISP tool such as stcgal. Windows + Keil µVision v5 only. See 部署指南.md (Chinese) for the full deployment guide, hard-won pitfalls (8051 0xSSSS_AAAA address-space encoding, GLink+ single-breakpoint limit, exit_debug crash), a real-world Qi wireless-charger debugging case, and smoke-test scripts in verify/.

License

MIT