stm32-mcp

MCP 服务器，让 Claude Code 能够构建、烧录并与 STM32 硬件通信。

stm32-mcp 非常针对我个人进行硬件开发的方式，但很可能对其他人也有用！它可以被调整以适应许多工作流程，但这是激光聚焦于我的工作流程（stlink-v3 mini、该接口上的 VCP、STM32 微控制器）。

你可以做类似这些事情：

我： 嘿，现在谁插着？

Claude： 两个未命名的探针连接着两块未命名的 PCB

我： 好，问问它们是谁，然后根据它们的回答给它们起个昵称

Claude： 明白了，你也想给探针起昵称吗？你的板子是“门铃 A”和“合成器 B”

我： 是的，我在那些探针上做了油漆标记。把门铃的叫做“蓝色”，合成器的叫做“红色”

Claude： 完成。接下来呢？

我： 给它们两个都发送 VCP 命令，让它们能互相通信，然后让门铃约合成器出去

Claude： 思考中... 完成，合成器拒绝了。天涯何处无芳草，门铃！

MCP（模型上下文协议） 是一个开放标准，允许像 Claude 这样的 AI 助手使用外部工具。这个服务器让 Claude 能够编译你的固件、将其烧录到板子、通过串口与之通信，并通过 SWD 读取内存。它灵活且具有对话性。

[!WARNING] 这个服务器让 AI 直接访问你的编译器、调试探针和串口。它可以烧录固件、覆盖内存，并向你的硬件发送任意数据。这强大且有用，但它不是沙箱。在让它大展身手之前，要清楚连接了什么。

先决条件

• STM32CubeIDE 安装在 /Applications/STM32CubeIDE.app（macOS）或 /opt/st/stm32cubeide_*（Linux）

• Python 3.10+

• OpenOCD（brew install open-ocd）——用于烧录、内存读写和实时监控

• 开源 stlink 工具（brew install stlink）——用于探针枚举

• ST-Link 通过 USB 连接（用于烧录/板卡信息）

• 串口可用（ST-Link VCP 或 USB-UART 适配器）

Related MCP server: jlink-mcp

安装

git clone https://github.com/shieldyguy/stm32-mcp.git
cd stm32-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

注册到 Claude Code

选项 A：CLI

claude mcp add stm32 -- /path/to/stm32-mcp/.venv/bin/python -m stm32_mcp.server

选项 B：项目配置

添加到你的项目的 .claude/settings.json 或 .claude.json：

{
  "mcpServers": {
    "stm32": {
      "command": "/path/to/stm32-mcp/.venv/bin/python",
      "args": ["-m", "stm32_mcp.server"]
    }
  }
}

自助 CLI

bin/ 包含四个薄包装器，封装了 MCP 工具使用的相同代码

将 bin/ 添加到你的 PATH：

export PATH="/path/to/stm32-mcp/bin:$PATH"

探针昵称和板卡昵称均可解析。

构建共享 MCP 的无头 CubeIDE 工作区锁，因此 stm32-build/stm32-bf 与代理驱动的构建竞争时，会排队等待。

可用工具

构建与烧录

多板管理

板卡昵称跟随物理 MCU（在探针更换后仍然保留）。探针昵称跟随 ST-Link 硬件。在所有工具的任何 probe 参数中都可以使用昵称。

串行通信

调试与监控

硬件序列

serial_sequence 在一次工具调用中调度多个步骤（串行发送、延迟、摄像头捕获和 SWD 内存读写）。延迟使用执行器线程中的 time.sleep()。Claude 无法可靠地计时单个工具调用，因此这允许对命令和预期进行紧密计时。

步骤类型

[
  { "send": "SIM_LEFT", "to": "/dev/cu.usbmodem11202" },
  { "delay_ms": 500 },
  {
    "send": "GET_BLINK_STATE",
    "to": "/dev/cu.usbmodem11402",
    "expect": "BLINK"
  },
  { "capture": true, "label": "post_brake" },
  {
    "mem_write": true,
    "address": "0x48000418",
    "value": "0x40",
    "probe": "yellow"
  },
  { "delay_ms": 1000 },
  {
    "mem_read": true,
    "address": "0x48000400",
    "count": 2,
    "probe": "yellow",
    "label": "gpio_post"
  }
]

• 发送步骤： {send, to, expect?, read_timeout?, line_ending?} — to 是来自 serial_connect 的端口路径

• 延迟步骤： {delay_ms} — 真正的 time.sleep()，不是工具调用往返

• 捕获步骤： {capture: true, label?, device_index?} — PNG 保存到 /tmp/stm32-captures/

• 内存写入步骤： {mem_write: true, address | symbol + elf_path, value, probe, width?}

• 内存读取步骤： {mem_read: true, address | symbol + elf_path, probe, count?, width?, label?}

内存步骤说明：

• probe 接受 ST-Link SN、探针昵称或板卡昵称

• address 是十六进制（例如 "0x48000418"）；或者使用 symbol + elf_path 按名称解析

• width 为 8/16/32 位，默认为 32（使用 symbol 时从符号大小自动检测）

• 每个内存操作目前都会启动一个新的 OpenOCD 进程（每次操作约几十毫秒的开销），因此内存操作之间的时间低于约 50 毫秒是近似的。延迟本身是准确的。

参数

• on_failure： "continue"（默认）无论结果如何都运行所有步骤。"stop" 在第一次失败时中止。

• filter_responses： 当为 true 时，expect 模式仅匹配以 > 为前缀的 VCP 响应行（忽略调试噪声）。

输出

Step 1 [/dev/cu.usbmodem11202] SEND: SIM_LEFT
  Response: >OK:SIM_LEFT

Step 2 DELAY: 500ms

Step 3 [/dev/cu.usbmodem11402] SEND: GET_BLINK_STATE
  Response: >BLINK_STATE:BLINK
  Expect "BLINK": PASS

Step 4 [yellow] MEM_WRITE: Wrote 0x00000040 to 0x48000418

Step 5 DELAY: 1000ms

Step 6 [yellow] MEM_READ: gpio_post 0x48000400: 0xabffdfff 0x00000080

Summary: 2/2 sends OK, 1/1 assertions PASS, 1/1 mem_writes OK, 1/1 mem_reads OK

实时内存监控

通过 SWD 实时监控固件变量，无需修改固件或使用串口。OpenOCD 作为持久子进程运行，并通过其内置的 TCL 套接字轮询变量。

启动会话

live_memory_start(
    variables='["blink", "ts"]',       # symbol names from ELF
    elf_path="/path/to/firmware.elf",
    probe="taillight",                  # board/probe nickname
    interval_ms=500                     # min 250ms
)

变量可以是：

• 符号名称（字符串）："blink" — 通过 arm-none-eabi-nm 从 ELF 解析

• 带有符号和类型的字典：{"symbol": "temperature", "type": "float"} — 将 32 位值解释为 IEEE 754

• 带有原始地址的字典：{"address": "0x20000304", "name": "x", "width": 32}

读取最近的值

live_memory_read(session_id="abc123", last_n=10)

返回内存环形缓冲区（最多 100 条）中的最近条目。完整历史记录写入 JSONL 输出文件。

JSONL 输出格式

{ "t": 1709830123.456, "elapsed_s": 1.002, "values": { "blink": 65539 } }

停止会话

live_memory_stop(session_id="abc123")

返回统计信息：持续时间、读取次数、错误次数、输出文件路径。

约束

• 每个探针一个会话 — 这是硬件约束（单个 SWD 连接）

• 烧录前停止 — live_memory 持有 SWD 连接；如果会话处于活动状态，stm32_flash 和 stm32_read/write_memory 将失败

• TCL 端口 6666 — OpenOCD 的默认端口。如果存在冲突，请先停止其他 OpenOCD 实例

串行默认值

• 波特率： 115200

• 行尾： LF（\n）

• 读取轮询： 50 毫秒字节间休眠，200 毫秒静默中断

• 缓冲区限制： 最大读取 4096 字节

开发

MCP 检查器

source .venv/bin/activate
mcp dev src/stm32_mcp/server.py

回环测试

串行工具可以在没有硬件的情况下使用 pyserial 的回环进行测试：

import serial
ser = serial.serial_for_url("loop://", baudrate=115200, timeout=0.1)
ser.write(b"PING\n")
print(ser.read(100))  # b'PING\n'