JLink MCP Server

🔌 让 AI 直接调试你的单片机 — 基于 Model Context Protocol (MCP)

通过本项目，Claude、Cursor 等 AI 助手可以直接通过 JLink 调试器控制单片机，实现：设置断点、单步执行、读写内存、读取变量、查看寄存器、RTT 日志、烧录固件等完整调试功能。

已在 STM32H7B0VB (Cortex-M7) 上完成真机验证，全部功能正常。

功能特性

• ✅ 连接管理 — 支持 SWD / JTAG，支持多 JLink、JLink over IP

• ✅ 断点控制 — 按地址或函数名设置/清除断点

• ✅ 执行控制 — 暂停、继续、单步、复位

• ✅ 内存读写 — 支持 8/16/32 位宽度，最大单次 1KB

• ✅ 寄存器读写 — 读写全部 CPU 核心寄存器（R0-R15、PC、SP、LR、xPSR 等）

• ✅ 变量调试 — 按变量名读写全局变量（自动解析 ELF/DWARF 调试信息）

• ✅ 符号解析 — 加载 .elf / .axf 获取函数地址、变量地址

• ✅ RTT 日志 — 读写 SEGGER RTT 实时通道

• ✅ 固件烧录 — 支持 .elf / .axf / .hex / .bin 格式

• ✅ 兼容 Keil MDK 和 CLion/CMake 工作流

目录结构

jlink-mcp/
├── server.py              # MCP 服务器主入口（25 个工具）
├── jlink_debugger.py      # JLink 操作封装（基于 pylink-square）
├── elf_parser.py          # ELF/DWARF 解析（变量名 → 地址 + 类型）
├── config.py              # 配置类 + 常用芯片型号表
├── requirements.txt       # Python 依赖
├── pyproject.toml         # 项目元数据
├── claude_desktop_config.json  # Claude Desktop 配置模板
├── test_jlink.py          # JLink 硬件检测脚本
├── test_full.py           # 完整功能测试脚本
└── README.md              # 本文档

环境要求

安装

# 进入项目目录
cd "jlink-mcp"

# 安装依赖（国内使用清华镜像）
python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple --trusted-host pypi.tuna.tsinghua.edu.cn

requirements.txt 内容：

mcp[cli]>=1.0.0
pylink-square>=0.12.0
pyelftools>=0.31

MCP 工具列表（25 个）

🔌 连接管理

▶️ 执行控制

🔴 断点管理

🧠 内存读写

📊 寄存器

📦 符号与变量（需加载 ELF）

📡 RTT 实时日志

💾 固件烧录

配置 AI 客户端

Claude Desktop

编辑：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "jlink-mcp": {
      "command": "python",
      "args": ["C:\\path\\to\\jlink-mcp\\server.py"]
    }
  }
}

注意：将路径替换为实际的 server.py 路径，然后重启 Claude Desktop。

Cursor

Settings → Features → MCP Servers → Add Server：

{
  "jlink-mcp": {
    "type": "stdio",
    "command": "python",
    "args": ["C:\\path\\to\\jlink-mcp\\server.py"]
  }
}

VS Code (Cline / Continue)

.vscode/mcp.json：

{
  "servers": {
    "jlink-mcp": {
      "type": "stdio",
      "command": "python",
      "args": ["C:\\path\\to\\jlink-mcp\\server.py"]
    }
  }
}

使用示例

基础调试流程

用户: 连接 STM32H7B0VB，SWD 接口
AI  → connect(device="STM32H7B0VB", interface="SWD")
   ← JLink S/N: 601012469, Core ID: 0x6ba02477, 已暂停

用户: 读取当前所有寄存器
AI  → read_registers()
   ← R0=0x00000000, PC=0x9008B598, SP=0x20006DD8...

用户: 在 main 函数设置断点，然后复位运行
AI  → load_elf("C:/Project/Debug/app.elf")
   → set_breakpoint(symbol="main")
   → reset(halt_after=False)
   ← 程序运行中，等待命中断点...

用户: 读取全局变量 g_counter 的值
AI  → read_variable(name="g_counter")
   ← name="g_counter", address=0x24000100, type="uint32_t", value=42

用户: 单步执行 5 次，查看 PC 变化
AI  → step(count=5)
   ← PC: 0x9008B598 → 0x9008B5A6

用户: 查看 RTT 日志输出
AI  → read_rtt()
   ← "[INFO] System init OK\r\n[INFO] Main loop start\r\n"

Keil MDK 工作流

1. Keil 编译项目（生成 .axf 和 .hex）

2. 关闭 Keil 调试会话（释放 JLink）

3. 对 AI 说：

   • "加载 ELF: C:\Keil_Projects\MyProject\Objects\MyProject.axf"

   • "连接 STM32F103C8"

   • "在 HAL_GPIO_WritePin 设置断点，运行"

CLion / CMake 工作流

1. CLion 构建项目（生成 .elf）

2. 停止 CLion 调试会话（释放 JLink）

3. 对 AI 说：

   • "加载 ELF: C:\Projects\MyApp\cmake-build-debug\MyApp.elf"

   • "连接 STM32F407VG"

常用芯片型号参考

真机测试结果

测试设备： STM32H7B0VB + J-Link V11 (S/N: 601012469)

常见问题

Q: 连接失败 "Cannot connect to J-Link"

确认 JLink USB 已插好，SEGGER J-Link 驱动已安装，目标板已供电。

Q: 找不到 JLinkARM.dll

安装 SEGGER J-Link Software Pack。 默认路径：C:\Program Files\SEGGER\JLink\JLinkARM.dll

Q: 变量读取提示"变量未找到"

1. 确认已调用 load_elf() 加载了 ELF 文件

2. 确认是全局变量（局部变量需要目标暂停在特定帧才能读取）

3. 确认编译时开启了调试信息（Keil: Debug，CLion: Debug 配置）

Q: Keil 和本工具能同时使用吗？

❌ 不能，JLink 同一时间只能被一个程序独占。使用本工具前请关闭 Keil 的调试会话。

Q: 支持 JTAG 吗？

支持，connect() 时传入 interface="JTAG" 即可。

Q: RTT 读取没有输出？

目标固件需要集成 SEGGER RTT 库，并调用 SEGGER_RTT_printf() 输出数据。

依赖说明

License

MIT License — 可自由使用、修改和分发。

开发信息

• 开发语言: Python 3.10+

• MCP 框架: FastMCP (mcp[cli])

• JLink 接口: pylink-square → JLinkARM.dll

• 符号解析: pyelftools (ELF/DWARF)

• 支持平台: Windows（JLinkARM.dll）

License

MIT — 详见 LICENSE。