mcp-stm32cubeide-server

An MCP (Model Context Protocol) server that lets AI coding agents (Claude Code / opencode / Claude Desktop) drive the full STM32 development loop — wire up → request → AI writes code → build → flash → debug → diagnose faults — end to end.

让 AI 编程助手（Claude Code / opencode / Claude Desktop 等）直接操控 STM32 开发全流程：接线 → 提需求 → AI 自己改代码 / 编译 / 烧录 / 验证。

中文文档为主。所有工具返回结构化 JSON，失败时携带明确错误信息，便于 AI 精确处理。

功能一览（17 个工具）

oled_add_zh_font 与波特律动取模助手/串口助手的字模完全一致（文泉驿点阵字，16x16 列行式阳码），无需再打开浏览器取模，取到的字模可直接用 OLED_PrintString 显示。

Related MCP server: agentic-hil

环境要求

• Python 3.10+，pip install -r requirements.txt（mcp>=1.0.0、pyserial>=3.5）

• 至少安装一个 ST 工具（CubeIDE / CubeMX / CubeProgrammer 任意组合）

工具链自动发现

按顺序查找：环境变量 → PATH → Windows 注册表 → 常见安装位置。大部分情况无需配置。

安装 / 注册

opencode — opencode.json

{
  "mcp": {
    "stm32cubeide": {
      "type": "local",
      "command": ["python", "D:\\path\\to\\mcp-stm32cubeide-server\\server.py"],
      "enabled": true
    }
  }
}

Claude Code / Claude Desktop — .mcp.json / claude_desktop_config.json

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

路径请替换为你克隆仓库后的实际路径。建议 command 使用 Python 绝对路径（避免 PATH 混入其他版本）。

典型自主编程流程

1. list_projects 找到工程

2. AI 直接修改源码 / 修改 .ioc 后 generate_code

3. build_project 编译（出错则读错误信息修到通过）

4. flash_firmware 或 debug_flash 烧录

5. serial_monitor 采集串口日志验证行为；崩溃则 debug_run 拿到故障寄存器诊断

6. 需要显示新汉字时，oled_add_zh_font 自动取模并集成进 font.c

运行测试

python -m unittest test_server -v

项目结构

server.py            # MCP 注册与工具路由（入口）
tools.py             # 各工具的 async 实现（含命令构造）
discovery.py         # 工具链路径发现（env / PATH / 注册表 / 浅层扫描 + 缓存）
process.py           # 子进程执行（超时杀进程树）+ OpenOCD 会话管理
mcu.py               # MCU 型号识别 + 故障寄存器诊断解析
project.py           # .ioc / .elf 查找、工程信息、工程扫描
serial_monitor.py    # 串口采集（pyserial，后台线程）
fontgen.py           # 汉字字模生成（波特律动官方取模接口 + 本地 PIL 兜底）
test_server.py       # 单元测试 / 冒烟测试

实现要点

• 全 async：所有工具为 async def，无嵌套 asyncio.run()，支持并发调用

• 进程树清理：Windows 超时用 taskkill /T /F，不残留 CubeIDE / OpenOCD

• OpenOCD 就绪探测：TCP 轮询端口而非固定 sleep；端口冲突自动避让

• 编码兼容：工具输出按 UTF-8 / GBK 自动解码，中文路径可用

• 安全：所有命令用参数列表传入（无 shell 注入面）；工具发现仅查已知位置

• 日志走 stderr：stdout 是 MCP 传输通道，不得污染

许可证

MIT