MCP server McuBuddy
✓ ПровереноПозволяет ИИ-ассистентам выполнять отладку реального микроконтроллерного оборудования, анализировать прошивку и проводить автоматизированную валидацию с помощью отладочных программаторов и Keil MDK.
Также известен как cunjun/McuBuddy
- Звёзды
- 10
- Инструменты
- —
- Загрузки, 30 дней
- 167
- Последняя версия
- 0.5.1
- Последний коммит
- 17 авг. 2026 г.
- Лицензия
- MIT
Что такое McuBuddy MCP?
Позволяет ИИ-ассистентам выполнять отладку реального микроконтроллерного оборудования, анализировать прошивку и проводить автоматизированную валидацию с помощью отладочных программаторов и Keil MDK.
Сводка сгенерирована из README проекта
О McuBuddy MCP server
Инженеры встраиваемых систем и разработчики могут выполнять отладку реального оборудования и автоматизированную валидацию напрямую через ИИ-ассистента. Подключаясь к таким программаторам, как ST-Link, J-Link или CMSIS-DAP, сервер позволяет ИИ проверять состояние процессора и памяти, регистры периферии через CMSIS-SVD и контексты задач FreeRTOS. Он устраняет разрыв между анализом кода и физическим оборудованием, предоставляя структурированные инструменты для диагностики прошивки и мониторинга состояния системы во время выполнения.
Пользователи, запускающие сервер на локальной машине, могут интегрировать его с такими клиентами, как Claude Code или Codex. Для пользователей Windows сервер может вызывать Keil MDK через UV4.exe для сборки проектов и прошивки микроконтроллеров. Система работает как исключительно локальный бэкенд через процесс stdio; для работы требуются целевая плата, программатор и доступные хост-машине файлы ELF или AXF. Возможности организованы в наборы инструментов, такие как probe, diagnose, build_flash, rtos и logs, для управления рабочим процессом отладки.
Что вы можете с ним делать
- 1Исследование сбоев прошивкиИИ может использовать данные ELF/DWARF для сопоставления адресов памяти с конкретными строками исходного кода и стеками вызовов во время HardFault.
- 2Автоматизация цикла сборки и прошивкиРазработчики могут давать ИИ команды на изменение кода, запуск сборки в Keil MDK и прошивку новой версии ПО в целевую плату.
- 3Мониторинг системных логов в реальном времениАссистент может считывать данные во время выполнения через UART, RTT или J-Link SWO для наблюдения за поведением системы.
- 4Анализ внутренних механизмов RTOSИИ может изучать задачи FreeRTOS и использование ими стека для выявления проблем с ресурсами.
Взято из README проекта. Каждый вариант использования проверен на соответствие цитате из него.
Как установить McuBuddy MCP
Форматы проверены 10 ноя 2026Добавить в CursorДобавить в GooseУстановка McuBuddy MCP в Claude Code
$ claude mcp add mcubuddy -- uvx McuBuddyУстановка McuBuddy MCP в Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcubuddy": {
"command": "uvx",
"args": [
"McuBuddy"
]
}
}
}Установка McuBuddy MCP в VS Code
.vscode/mcp.json
{
"servers": {
"mcubuddy": {
"type": "stdio",
"command": "uvx",
"args": [
"McuBuddy"
]
}
}
}Установка McuBuddy MCP в VS Code CLI
$ code --add-mcp '{"name":"mcubuddy","type":"stdio","command":"uvx","args":["McuBuddy"]}'Установка McuBuddy MCP в Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcubuddy": {
"command": "uvx",
"args": [
"McuBuddy"
]
}
}
}Установка McuBuddy MCP в Codex
$ codex mcp add mcubuddy -- uvx McuBuddyУстановка McuBuddy MCP в Codex config.toml
~/.codex/config.toml
[mcp_servers.mcubuddy] command = "uvx" args = ["McuBuddy"]
Установка McuBuddy MCP в Gemini CLI
$ gemini mcp add -s user mcubuddy uvx -- McuBuddyУстановка McuBuddy MCP в Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcubuddy": {
"command": "uvx",
"args": [
"McuBuddy"
]
}
}
}Автоматические проверки
Запущено 14 нояб. 2026 г.Полный отчёт →Прошло наши автоматизированные проверки. Это не аудит безопасности: изучите код и предоставьте серверу минимально необходимый доступ. Как работают проверки
- Связанный и доступный исходный репозиторийcunjun/mcubuddy is public and reachablegithub.com/cunjun/mcubuddy ↗Пройдено
- Пакет указывает этот репозиторий как источникMcuBuddy names cunjun/mcubuddy as sourcepypi.org/project/McuBuddy/ ↗Пройдено
- Происхождение сборки (аттестация Sigstore)No build attestation published for this releaseНе проверялось
- Open source лицензия (OSI)MITspdx.org/licenses/MIT.html ↗Пройдено
- Коммит или релиз за последний годLast commit or release 2026-08-17github.com/cunjun/mcubuddy ↗Пройдено
- OpenSSF ScorecardНе проверялось
- Имя пакета не похоже на популярный пакетNo popular package one edit away from McuBuddyПройдено
- Нет критических предупреждений в пакете или его зависимостях55 resolved dependencies checked; no critical advisoryosv.dev ↗Пройдено
- Нет скрытых инструкций для модели0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersПройдено
- Деструктивные инструменты помеченыНе проверялось
- Удалённая конечная точка отвечает на рукопожатие MCPНе проверялось
README
Открыть на GitHubMcuBuddy — AI-Powered MCU and Embedded Firmware Debugging MCP Server
Extend AI from firmware analysis to real MCUs, closing the loop across diagnosis, code changes, build, flashing, and validation in verified environments.
McuBuddy is a Model Context Protocol (MCP) server for
MCU board-level debugging. It exposes debug probes, Keil MDK projects, ELF/DWARF symbols,
CPU and memory state, SVD peripheral registers, UART/RTT logs, FreeRTOS state, Flash operations,
and GDB servers as structured tools that AI assistants can call.
It is designed for firmware development, board bring-up, fault isolation, debugging automation, and AI-assisted validation.
McuBuddy starts with 19 stable tools in the default toolset. Add only the domains a workflow
needs with MCUBUDDY_TOOLSETS=probe,diagnose (available domains: probe, diagnose,
build_flash, rtos, logs, and experimental). The core profile is the only profile;
startup toolset selection is explicit and immutable.
[!IMPORTANT] Automation does not replace engineering responsibility. Humans remain responsible for goals and acceptance criteria, wiring and power safety, high-risk operation approval, code review, and new environment validation. Motors, relays, and other safety-related devices also require recovery plans and independent protection.
Quick links: Quick Start · Project Guide · Tool Reference · Support Matrix
✨ Key Features
- Real-hardware debugging: Discover and connect to ST-Link, J-Link, CMSIS-DAP, and other probes; control target execution; and inspect registers, memory, breakpoints, and watchpoints.
- Keil project workflow: Discover
.uvprojx/.uvprojfiles, select a target, invoke Keil MDK throughUV4.exefor builds or downloads, and feed the generated AXF/ELF into debugging. - Source-level fault diagnosis: Use ELF/DWARF data to resolve addresses to functions, source lines, local variables, and call stacks when investigating HardFaults, startup failures, stack overflows, and memory corruption.
- Peripheral and RTOS inspection: Decode peripheral registers through CMSIS-SVD and inspect FreeRTOS tasks, task contexts, and stack usage.
- Logs and runtime observability: Read UART, RTT, and selected J-Link SWO logs, and manage pyOCD/J-Link GDB server lifecycles.
- Evidence-driven results: Return structured target, state, and validation evidence so AI can continue an investigation instead of guessing code changes from symptoms alone.
- Actionable hardware boundaries: Distinguish MCU limitations, firmware-inapplicable tools, configuration problems, tool failures, and insufficient evidence, including impact and the next safe check so unsupported paths are not debugged as firmware defects.
🏗️ How It Works
flowchart LR
AI["AI Client<br/>Codex / Claude Code"] --> MCP["McuBuddy<br/>MCP Server"]
MCP --> EB["Execution Boundary<br/>Serialized Session"]
EB --> TOOLS["Debugging Tools<br/>Diagnostics / Symbols / SVD / RTOS / Logs"]
TOOLS --> KEIL["Keil MDK / UV4.exe<br/>Build / Optional Download"]
TOOLS --> PROBE["Probe Backends<br/>pyOCD / J-Link / probe-rs"]
KEIL --> IMAGE["AXF / ELF / HEX / BIN"]
IMAGE --> TOOLS
PROBE --> BOARD["Real MCU Board"]
MCP is not a protocol for invoking Keil. The AI calls McuBuddy through MCP; McuBuddy then
uses Keil MDK through UV4.exe, pyOCD, J-Link, or another internal backend as required.
🚀 Quick Start
1. Prerequisites
Basic requirements:
- Python 3.10 or later;
- a powered MCU development board;
- a correctly connected ST-Link, J-Link, or CMSIS-DAP probe;
- the target chip name;
- preferably, an ELF/AXF image containing debug information.
Keil build and download features require Windows with Keil MDK installed. McuBuddy invokes
µVision through UV4.exe, including in Keil MDK v5 installations.
2. Installation
pip install "McuBuddy @ git+https://github.com/cunjun/McuBuddy.git"
This installs McuBuddy once for all local firmware projects. Do not clone or copy the McuBuddy
repository into each target project. McuBuddy is a local-only MCP backend: the client starts one
stdio process per connection, and McuBuddy does not expose HTTP, SSE, WebSocket, or another MCP
network listener.
The target project, Keil installation, ELF/SVD files, probe, and serial port must be directly
visible to the machine running McuBuddy. To update, reinstall from the official repository at
https://github.com/cunjun/McuBuddy; McuBuddy never checks for, downloads, or installs updates
automatically.
Install the optional dependency when using the J-Link Python backend:
pip install "McuBuddy[jlink]"
For development from source:
git clone https://github.com/cunjun/McuBuddy.git
cd McuBuddy
pip install -e ".[dev]"
3. Configure an MCP Client
{
"mcpServers": {
"McuBuddy": {
"command": "McuBuddy",
"args": []
}
}
}
For a Windows source checkout, explicitly configure the virtual-environment Python executable and working directory. See Installation and First Connection, then restart the AI client.
4. Run a First Read-Only Check
After connecting the probe and powering the board, tell the AI:
Use McuBuddy to inspect the current debugging environment, discover connected probes,
and perform a first read-only check of the board without writing Flash.
Before starting, tell me what information is still missing.
The recommended sequence is to check the environment and target first, then configure the probe and read the minimum target state:
doctor()
list_connected_probes()
match_chip_name("py32f030x8")
configure_probe(target="py32f030x8", backend="pyocd")
probe_connect(target="py32f030x8")
read_stopped_context()
probe_connect and read_stopped_context are available in the default core profile. Reading a
stable stopped context may halt the target, so it is still execution-changing. If the device must
not be halted, instruct the AI to perform only non-intrusive probe and environment checks.
💬 Automated Debugging Example
Use McuBuddy to debug <project path>. The MCU is <exact model>, and the probe is
<ST-Link/J-Link/CMSIS-DAP>. First collect board-level evidence and locate the problem. After
authorization, modify the code, build and flash it, then validate the result on the real board.
For the evidence-first decision order and common scenarios, see Common Debugging Workflows.
🧰 Backends and Hardware Validation
| Path | Current Role | Main Capabilities |
|---|---|---|
| pyOCD + ST-Link/CMSIS-DAP | Primary backend | Control, memory, Flash, source debugging, RTT, RTOS, and GDB server |
| J-Link | Primary backend | Control, memory, Flash, source debugging, native RTT, DWT, and GDB server |
| probe-rs sidecar | Extended preview | ARM/RISC-V/Xtensa discovery, configurable core control, registers, memory, hardware breakpoints, Flash, and RTT |
Keil MDK (Windows, via UV4.exe) |
Build/download backend | Project discovery, target configuration, build, logs, and optional download; supports MDK v5 installations |
Primary validation coverage includes:
- STM32L496VETx + ST-Link / pyOCD;
- STM32F103C8 + J-Link;
- built-in target preflight profiles for STM32F103ZE and PY32F030X8.
“Implemented in code” does not mean “validated on every board.” Use the
Support Matrix and list_validation_records() as the source of truth.
🛡️ Safety Model
McuBuddy provides machine-readable safety classifications through list_tool_safety().
| Category | Examples | Default Requirement |
|---|---|---|
| Read-only | Target matching, register/memory reads, symbol resolution, logs, diagnostics | No confirmation required |
| Execution-changing | halt, resume, reset, continue, stepping | Does not write Flash, but changes execution state |
| Runtime-state write | Memory/register writes, breakpoints, watchpoints, SVD field writes | Explicit confirmation |
| Persistent destructive operation | Flash erase/program, Keil firmware download | Explicit confirmation |
| Host process | Keil build, GDB server start/stop | Starts or stops a local process |
Safety principles:
- For an unknown target, match the chip and probe first; do not guess addresses.
- Read evidence before halting, resetting, or writing.
- Before a Flash operation, confirm the target, scope, image, and recovery method.
- For motors, relays, power switches, and other actuators, prefer breakpoints and low-energy tests.
- Send actuator commands with
uart_send_with_cleanup, then callfinish_debug_sessionbefore returning a final conclusion. Server shutdown repeats the same idempotent cleanup as a fallback.
🔒 Sessions and Concurrency
- Operations that share probe, Keil, ELF/SVD, log, and runtime configuration are serialized within
the same
Session. - Different sessions can run concurrently when they control unrelated boards.
- Stateless queries such as target matching and tool safety information can run alongside session operations.
- Cancellation cannot forcibly terminate a call that has entered a synchronous SDK. The server waits for the worker thread to finish before releasing the session lock.
This prevents one request from switching backends, disconnecting the probe, or changing shared state while another probe operation is still running.
📦 mcubuddy Skill
The repository includes skills/mcubuddy, which guides Codex and Claude Code to use these tools in an
“evidence first, judgment second” sequence instead of treating MCP tools as an unordered command list.
The Skill is an optional workflow enhancement, not a prerequisite for hardware debugging. A correctly installed and configured local McuBuddy MCP server remains fully usable without it.
Installed releases bundle the Skill. Register the persistent Codex integration without cloning the repository:
uv tool install McuBuddy
McuBuddy setup codex --confirm --json
Install for Codex:
python .\skills\mcubuddy\scripts\install_skill.py --target codex --overwrite
Install for Claude Code:
python .\skills\mcubuddy\scripts\install_skill.py --target cc --overwrite
Restart the client or open a new session after installation. For source-checkout recovery, installation registration, and usage boundaries, see Boundaries Between McuBuddy, MCP, and the Skill for details.
⚠️ Current Limitations
- Keil build and download currently require Windows with Keil MDK and invoke µVision through
UV4.exe, including in MDK v5 installations. - The probe-rs sidecar covers Flash and RTT but still requires target-specific real-board validation and does not yet have an official binary release.
- RTOS inspection depends on FreeRTOS symbols and an ELF/AXF that match the target firmware.
- SVD files are not bundled automatically for every chip and usually come from a CMSIS-Pack or the chip vendor.
- SWO text capture depends on chip configuration, probe capabilities, pin multiplexing, and board wiring.
- Device patches and connection strategies remain lightweight mechanisms rather than a complete board plugin system.
📚 Documentation
- Complete project overview and workflows: Project Guide
- Chinese project overview: 项目指南
- Complete tool index: Tool Reference
- Chinese tool usage: MCP 工具中文参考
- Backend and hardware validation: Support Matrix
- Project design: Architecture
- Release history: Changelog
🧪 Local Development
pip install -e ".[dev]"
pytest
ruff check src tests
See the Project Guide for repository layout and documentation ownership.
🙏 Upstream and Acknowledgements
McuBuddy is based on SolarWang233/mcudbg and continues its MIT-licensed work with additional architecture, safety boundaries, evidence workflows, backend support, and documentation. The original copyright notice is preserved in LICENSE, with provenance details in NOTICE.
📄 License
This project is licensed under the MIT License. See LICENSE for details.
If McuBuddy helps with your MCU debugging workflow, consider giving the project a Star.
If you have suggestions, open an Issue or email
zhou229449@gmail.com.
Вопросы о McuBuddy MCP
Как добавить McuBuddy MCP в Claude Code?
Выполните claude mcp add mcubuddy -- uvx McuBuddy в терминале. Добавьте --scope user, чтобы сервер был доступен во всех проектах.
Как добавить McuBuddy MCP в Cursor?
Откройте ~/.cursor/mcp.json и добавьте сервер в mcpServers, используя конфигурацию Cursor из раздела установки выше.
Какие аппаратные программаторы поддерживает McuBuddy?
Он поддерживает ST-Link, J-Link, CMSIS-DAP и другие программаторы через такие бэкенды, как pyOCD и probe-rs.
Требуется ли Windows для интеграции с Keil?
Да, функции сборки и прошивки Keil требуют наличия Windows с установленным Keil MDK для вызова µVision через UV4.exe.
Может ли McuBuddy проверять состояния RTOS?
Да, он может анализировать задачи FreeRTOS, их контексты и использование стека, используя символы ELF/AXF.
Является ли сервер сетевым сервисом?
Нет, это локальный MCP бэкенд, который использует stdio для связи и не предоставляет доступ через HTTP или WebSockets.