STM32Cube-MCP
Provides control over STM32CubeIDE and the STMicroelectronics embedded ecosystem, enabling project scaffolding, headless builds, hardware flashing, memory/register inspection, GDB debugging, and UART telemetry for STM32 devices.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@STM32Cube-MCP Build the project in STM32CubeIDE and report flash usage."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
β‘ Overview
STM32Cube-MCP turns your favorite LLM or AI coding agent (Claude Desktop, Antigravity IDE, Cursor, Windsurf, or VS Code) into an elite embedded systems engineer with 100% full-app autonomy over STM32CubeIDE and the STMicroelectronics hardware ecosystem.
Gone are the days when AI could only write code in a vacuum. With STM32Cube-MCP, AI agents can:
Launch, Focus & Drive the IDE GUI: Open projects, send Eclipse keyboard shortcuts (
Ctrl+B,F11,Ctrl+F11), capture real-time window screenshots, and manage dialogs.Headless Build Engine: Compile, clean, and re-index projects headlessly via
headless-buildandstm32cubeidec, then parse exact Flash and RAM memory footprints (arm-none-eabi-size).Physical Hardware Flashing: Auto-discover ST-LINK v2/v3 probes, DFU devices, J-Link adapters, flash binaries (
.elf,.hex,.bin), mass-erase, and reset targets with verification.Deep Silicon Inspection: Read and write 32-bit registers/memory addresses live, configure hardware option bytes (RDP, BOR, Watchdog), and dump flash firmware.
GDB Server & Remote Debugging: Spin up
ST-LINK_gdbserveroropenocdon demand, attacharm-none-eabi-gdb, halt cores, inspect registers, evaluate backtraces, and set breakpoints.Live Hardware Telemetry (UART): Stream
printflogs and FreeRTOS telemetry directly to the agent over serial COM ports.CubeMX .ioc Engineering: Parse, scaffold, and mutate STM32CubeMX
.iocpinout definitions, clock trees, and peripheral drivers programmatically.
Related MCP server: vscode-cube-mcp
ποΈ Architecture
ββββββββββββββββββββββββββββ
β AI Assistant / Agent β
β (Claude/Cursor/Antigravity)
ββββββββββββββ¬ββββββββββββββ
β MCP (stdio / sse)
βΌ
ββββββββββββββββββββββββββββ
β STM32Cube-MCP β
β (34 Tools) β
βββββ¬βββββββ¬βββββββ¬βββββββ¬ββ
ββββββββββββββββββββββ β β ββββββββββββββββββββββ
βΌ βΌ βΌ βΌ
ββββββββββββββββββββββ βββββββββββββββ ββββββββββββββββ ββββββββββββββββ
β IDE Controller β β Headless β β Programmer β β GDB Server β
β & Win32/GUI β β Build Bat β β CLI Engine β β & OpenOCD β
ββββββββββββ¬ββββββββββ ββββββββ¬βββββββ ββββββββ¬ββββββββ ββββββββ¬ββββββββ
β β β β
βΌ βΌ βΌ βΌ
ββββββββββββββββββββββ βββββββββββββββ ββββββββββββββββ ββββββββββββββββ
β stm32cubeide.exe β β CDT Build β β ST-LINK β β arm-none- β
β (GUI Window/Keys) β β Compiler β β Flash/Memory β β eabi-gdb β
ββββββββββββββββββββββ βββββββββββββββ ββββββββββββββββ ββββββββββββββββπ Key Features
Capability | Description |
π₯οΈ Full GUI Control | Launch STM32CubeIDE, bring window to front, send shortcuts ( |
βοΈ Headless Compilation | Run automated headless builds via |
π Memory Footprint | Analyze |
π Probe Discovery | Auto-detect connected ST-LINK v2/v3 probes with hardware serial numbers, DFU bootloader devices, and COM ports. |
β‘ Hardware Flashing | Flash |
π¬ Memory & Option Bytes | Read/write raw 32-bit registers (GPIO, RCC, NVIC), modify readout protection (RDP), brown-out reset, and watchdog option bytes. |
π GDB Debug Automation | Background |
π‘ Serial UART Monitor | Bidirectional COM port / UART monitor to read MCU |
π CubeMX .ioc Engine | Programmatically inspect and modify |
π§© Project Scaffolder | Scaffold ready-to-build STM32 projects ( |
π Cross-Platform | Native zero-dependency path discovery across Windows, macOS, and Linux. |
π¦ Installation
Option 1: Run Instantly with uvx (Recommended)
No installation required! uvx will automatically fetch and launch the MCP server in an isolated environment:
uvx --from git+https://github.com/brovk2008/STMcube-MCP.git stm32cube-mcpOption 2: Install via pip
git clone https://github.com/brovk2008/STMcube-MCP.git
cd STMcube-MCP
pip install -e .Verify your installation:
stm32cube-mcp --detect-onlyOutput:
{
"ide_executable": "C:\\ST\\STM32CubeIDE_2.2.0\\STM32CubeIDE\\stm32cubeide.exe",
"programmer_cli": "...\\STM32_Programmer_CLI.exe",
"stlink_gdbserver": "...\\ST-LINK_gdbserver.exe",
"arm_gcc": "...\\arm-none-eabi-gcc.exe",
"version": "2.2.0",
"platform_name": "Windows"
}π οΈ Configuration for MCP Clients
1. Antigravity IDE
Add to your mcp_config.json (~/.gemini/antigravity-ide/mcp_config.json):
{
"mcpServers": {
"stm32cube": {
"command": "python",
"args": ["-m", "stm32_mcp"]
}
}
}2. Claude Desktop
Add to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
{
"mcpServers": {
"stm32cube": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/brovk2008/STMcube-MCP.git",
"stm32cube-mcp"
]
}
}
}3. Cursor & Windsurf
In Cursor/Windsurf MCP Settings, add a new command server:
Name:
stm32cubeCommand:
pythonArgs:
["-m", "stm32_mcp"]
π§° Complete Tool Catalog (34 Tools)
1. Toolchain & Probe Discovery
Tool | Description |
| Auto-detects IDE installation, version, and all bundled CLI/GDB/GCC tools. |
| Returns IDE running status, PIDs, memory usage, open windows, and active probes. |
| Discovers ST-LINK probes (with SNs), DFU devices, J-Link, and serial ports. |
| Queries target MCU silicon for Device ID, Device Name, and Flash size. |
2. IDE Lifecycle & GUI Automation
Tool | Description |
| Opens STM32CubeIDE GUI with optional workspace, project, or file path. |
| Closes running IDE instances gracefully or forcefully. |
| Brings the STM32CubeIDE window to the foreground. |
| Lists all open IDE windows, dialogs, titles, and screen coordinates. |
| Sends keyboard shortcuts ( |
| Captures high-res screenshot of IDE window or desktop as base64 PNG. |
3. Project & CubeMX Workspace Management
Tool | Description |
| Discovers all STM32 projects in a directory with target MCU and |
| Scaffolds complete STM32 project ( |
| Imports a project into the headless Eclipse workspace. |
| Removes a project from the headless workspace. |
| Extracts MCU family, CPU type, clock frequency, pinouts, and enabled IPs from |
| Updates or adds configuration parameters in a CubeMX |
4. Headless Compilation & Memory Analysis
Tool | Description |
| Triggers headless build ( |
| Performs clean build on project or workspace. |
| Locates |
5. Flashing, Erasing & Memory Control
Tool | Description |
| Flashes firmware with readback verification and auto-reset. |
| Performs chip mass erase or sector erase. |
| Triggers software or hardware NRST pin reset. |
| Reads 32-bit words from registers, RAM, or Flash. |
| Writes 32-bit values directly to memory or hardware registers. |
| Dumps hardware option bytes (RDP, BOR, WDG, Boot). |
| Modifies device option bytes. |
| Dumps firmware from target MCU into a local file. |
6. Debugging & GDB Server
Tool | Description |
| Starts background |
| Launches OpenOCD with target/interface scripts. |
| Terminates active GDB server processes. |
| Executes automated batch GDB session (registers, backtrace, breakpoints). |
7. Serial Telemetry & UART
Tool | Description |
| Lists all available COM / UART ports with hardware IDs. |
| Captures incoming UART telemetry / |
| Sends commands or strings to the MCU over UART. |
π¬ Example Prompts for Your AI
Once connected, you can ask your AI:
"Check my connected ST-LINK probes, create a new STM32F401RETx blinky project, build it, and flash it to the board with verification."
"Open STM32CubeIDE with my project, focus the window, trigger a build shortcut, and take a screenshot of the IDE build console."
"Connect to my target MCU over SWD, read the option bytes, and check if Readout Protection (RDP) is active."
"Start the ST-LINK GDB server, connect with GDB, halt the target, and dump the core registers."
"Listen to COM4 at 115200 baud for 5 seconds and show me the latest sensor readings from the MCU."
π Cross-Platform Support
STM32Cube-MCP is engineered for cross-platform reliability:
Windows: Full Win32 API window control, process discovery, bundled
headless-build.bat, andSTM32_Programmer_CLI.macOS: Auto-detects
/Applications/STM32CubeIDE.app, AppleScript UI activation, and standard Homebrew / ST toolchains.Linux: Auto-detects
/opt/st/stm32cubeide,wmctrl/xdotoolwindow management, and standard system paths.
π€ Contributing
Contributions, issues, and feature requests are welcome! Check out CONTRIBUTING.md and our CODE_OF_CONDUCT.md.
π License
This project is licensed under the Apache License 2.0 © 2026 Vaibhav Kumar (@brovk2008).
Available Tools
34 toolsstm32_build_projectA
Executes a headless build of a project in an STM32CubeIDE workspace using headless-build.
Args: workspace_path: Path to the Eclipse workspace folder. project_name: Specific project name to build (or None for all projects). configuration: Build configuration ('Debug' or 'Release'). clean_first: If True, performs a clean build (-cleanBuild). no_indexer: Disables Eclipse indexer during build for speed.
Inputs: workspace_path (required), no_indexer, clean_first, project_name, +1 more. Returns: result
stm32_capture_ide_screenshotA
Captures a screenshot of the STM32CubeIDE window or desktop. Returns dimensions, base64 PNG data, and optionally saves to local file.
Inputs: save_path, window_only. Returns: result
stm32_clean_projectC
Cleans build artifacts for a project or workspace headlessly.
Inputs: workspace_path (required), project_name, configuration. Returns: result
stm32_close_ideA
Closes running STM32CubeIDE instances.
Args: force: If True, forcefully terminates the processes. Otherwise closes gracefully.
Inputs: force. Returns: result
stm32_create_projectA
Scaffolds a new, ready-to-build STM32 project:
.project: Eclipse CDT project definition
<project_name>.ioc: STM32CubeMX configuration file
Core/Src/main.c: Standard embedded main entry point with LED blink loop
Core/Inc/main.h: Embedded header file
STM32_FLASH.ld: Linker script for Flash & RAM section mappings
Makefile: Standalone GNU ARM build script
Inputs: project_name (required), target_mcu, destination_dir. Returns: result
stm32_detect_installationA
Auto-detects the STM32CubeIDE installation path and all bundled toolchains:
Base IDE directory and detected version
stm32cubeide executable and console launcher
headless-build script
STM32_Programmer_CLI executable
ST-LINK_gdbserver executable
OpenOCD executable
GNU ARM toolchain (arm-none-eabi-gcc, gdb, size, objcopy)
Inputs: no named parameters. Returns: result
stm32_dump_flash_to_fileB
Reads flash memory contents from the target MCU and dumps them to a local file.
Inputs: port, address, size_bytes, output_file. Returns: result
stm32_erase_flashA
Erases target flash memory.
Args: mode: 'all' for full chip mass erase, or 'sectors' with start_address and end_address. start_address: Start address (e.g. '0x08000000') for sector erase. end_address: End address (e.g. '0x08004000') for sector erase. port: Connection port ('SWD', 'JTAG', 'URT').
Inputs: mode, port, end_address, start_address. Returns: result
stm32_flash_firmwareA
Flashes firmware (.elf, .hex, or .bin) onto the target STM32 microcontroller.
Args: file_path: Path to compiled binary (.elf, .hex, .bin). address: Flash start address (required for raw .bin files, e.g. '0x08000000'). verify: Verify flash write after programming. reset: Reset target MCU after programming. port: Debug interface ('SWD', 'JTAG', 'URT', 'USB1'). freq_khz: Debug probe clock frequency in kHz. start_run: Start firmware execution immediately.
Inputs: file_path (required), port, reset, verify, +3 more. Returns: result
stm32_focus_ide_windowA
Brings the STM32CubeIDE main window to the foreground and restores it if minimized.
Inputs: no named parameters. Returns: result
stm32_get_build_artifactsB
Inspects built binaries (.elf, .hex, .bin, .map) in the project output directory. Uses arm-none-eabi-size to analyze text, data, bss sections, and calculates total Flash and RAM usage.
Inputs: project_dir (required), configuration. Returns: result
stm32_get_ide_windowsA
Lists all open STM32CubeIDE windows, dialogs, coordinates, and window titles.
Inputs: no named parameters. Returns: result
stm32_get_system_statusB
Checks the real-time operational status of STM32CubeIDE on the host system:
Whether the IDE GUI is currently running
PIDs, memory usage, and runtime of STM32 processes
Open STM32CubeIDE windows and dialog titles
Connected debug probes (ST-LINK, DFU, COM ports)
Inputs: no named parameters. Returns: result
stm32_get_target_infoB
Connects to the physical STM32 microcontroller and retrieves hardware device info:
Device ID (e.g. 0x423 for STM32F401, 0x410 for STM32F103)
Device name and core architecture
Flash memory size
Connection status
Inputs: port, freq_khz. Returns: result
stm32_import_projectC
Imports an existing STM32Cube project into an Eclipse workspace headlessly.
Args: workspace_path: Path to the target workspace folder. project_dir: Path to the project root folder containing .project.
Inputs: project_dir (required), workspace_path (required). Returns: result
stm32_launch_ideA
Opens/launches the STM32CubeIDE desktop application.
Args: workspace_path: Optional path to open a specific Eclipse workspace directory. project_path: Optional path to open a specific STM32 project. file_to_open: Optional path to a specific source file (e.g. main.c) to edit. clean: If True, passes -clean to refresh Eclipse OSGi bundles.
Inputs: clean, file_to_open, project_path, workspace_path. Returns: result
stm32_list_connected_probesA
Scans for all connected STM32 hardware interfaces and debug probes:
ST-LINK probes with serial numbers and firmware versions
STM32 devices in DFU (USB bootloader) mode
J-Link adapters
Available serial / UART COM ports
Inputs: no named parameters. Returns: result
stm32_list_projectsA
Recursively scans a workspace or root directory and discovers all STM32 projects. Returns project names, paths, detected target MCUs, and whether .ioc files exist.
Inputs: root_dir (required). Returns: result
stm32_list_serial_portsA
Lists all available UART / COM serial ports on the host system with hardware descriptions.
Inputs: no named parameters. Returns: result
stm32_parse_iocA
Parses an STM32CubeMX .ioc file and returns:
MCU Target name & Family (e.g. STM32F4, STM32G4)
CPU core type (Cortex-M4, Cortex-M7, etc.)
System clock frequency in Hz
Configured GPIO pins, labels, and modes
Enabled IPs (USART, SPI, I2C, CAN, ADC, FreeRTOS, etc.)
Inputs: ioc_path (required). Returns: result
stm32_read_memoryA
Reads 32-bit words from target memory address (registers, RAM, or Flash).
Args: address: Target memory hex address (e.g. '0x08000000' or '0x40020000'). size: Number of 32-bit words to read. port: Connection interface ('SWD', 'JTAG').
Inputs: port, size, address. Returns: result
stm32_read_option_bytesB
Reads device option bytes (Read Out Protection RDP, Brownout Reset BOR, Watchdog, Boot).
Inputs: port. Returns: result
stm32_read_serialB
Listens and captures incoming serial output from target UART (e.g. printf output or RTOS telemetry).
Args: port: Port name (e.g. 'COM3' or '/dev/ttyUSB0'). baudrate: Baud rate (default: 115200). timeout_sec: Listening window in seconds. max_bytes: Maximum bytes to read.
Inputs: port (required), baudrate, max_bytes, timeout_sec. Returns: result
stm32_remove_projectB
Removes a project from the headless Eclipse workspace.
Inputs: project_name (required), workspace_path (required). Returns: result
stm32_reset_targetA
Triggers a target MCU reset via debug probe.
Args: hard_reset: If True, pulses the hardware NRST pin (-hardRst). Otherwise software system reset. port: Connection port ('SWD', 'JTAG').
Inputs: port, hard_reset. Returns: result
stm32_run_gdb_scriptA
Executes an automated GDB batch session against target MCU using arm-none-eabi-gdb.
Args: commands: List of GDB commands (e.g. ['monitor reset halt', 'info registers', 'bt']). elf_file: Optional path to compiled .elf file with debug symbols. remote_port: Port of active GDB server (connects to localhost:). timeout_sec: Maximum execution timeout in seconds.
Inputs: commands (required), elf_file, remote_port, timeout_sec. Returns: result
stm32_send_ide_shortcutA
Sends Eclipse keyboard shortcuts directly to the STM32CubeIDE window.
Supported actions:
'build': Build active project (Ctrl+B / Cmd+B)
'debug': Start debug session (F11)
'run': Run target (Ctrl+F11)
'step_into': Debug step into (F5)
'step_over': Debug step over (F6)
'step_return': Debug step return (F7)
'resume': Debug resume execution (F8)
'terminate': Stop/terminate debug (Ctrl+F2)
'save_all': Save all open files (Ctrl+Shift+S)
'open_resource': Open resource dialog (Ctrl+Shift+R)
'quick_access': Focus Quick Access bar (Ctrl+3)
Inputs: action (required). Returns: result
stm32_start_gdb_serverA
Starts the bundled ST-LINK_gdbserver as a background process listening on specified TCP port.
Args: port: GDB TCP port (default: 61234). probe_index: ST-Link probe index to bind. verify: Verify flash write during GDB load. persistent: Keep server active between disconnects (-p).
Inputs: port, verify, persistent, probe_index. Returns: result
stm32_start_openocdC
Starts OpenOCD with specified configuration scripts.
Inputs: port, config_files. Returns: result
stm32_stop_gdb_serverA
Stops all running ST-LINK_gdbserver or OpenOCD processes.
Inputs: no named parameters. Returns: result
stm32_update_iocA
Updates or inserts a configuration property in an STM32CubeMX .ioc file (e.g. key='RCC.SYSCLKFreq_VALUE', value='84000000').
Inputs: key (required), value (required), ioc_path (required). Returns: result
stm32_write_memoryB
Writes a 32-bit word directly to a target memory address or peripheral register.
Args: address: Target address (e.g. '0x20000000'). value: Hex value to write (e.g. '0x12345678'). port: Connection interface ('SWD', 'JTAG').
Inputs: value (required), address (required), port. Returns: result
stm32_write_option_bytesB
Modifies hardware option bytes (e.g. options=['RDP=0xAA', 'BOR_LEV=0']).
Inputs: options (required), port. Returns: result
stm32_write_serialB
Sends data or AT/terminal commands to target MCU over serial port.
Args: port: Port name (e.g. 'COM3' or '/dev/ttyUSB0'). data: String to send. baudrate: Baud rate (default: 115200). append_newline: If True, appends CRLF (\r\n).
Inputs: data (required), port (required), baudrate, append_newline. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 34 tools
Most tools target a distinct resource and action, but a few overlaps exist: stm32_get_system_status includes connected debug probes and COM ports, which also appear in stm32_list_connected_probes and stm32_list_serial_ports. Additionally, stm32_start_openocd and stm32_start_gdb_server both start debug servers, with stm32_stop_gdb_server stopping both.
All tools follow the consistent stm32_<verb>_<object> pattern with snake_case throughout, e.g. list_projects, create_project, read_memory, and write_serial. Even longer names like dump_flash_to_file and start_gdb_server fit the same predictable convention.
At 34 tools, the server exceeds the 25-tool threshold and feels heavy for an MCP surface. The IDE-window automation cluster, serial-port listing, and debug-server controls could reasonably be consolidated without losing core functionality.
The tool set covers the full embedded workflow: project creation/import/build/flash, memory access, option bytes, serial I/O, GDB server control, and IDE automation. Minor gaps remain such as CubeMX code generation and project rename/configuration management, but agents can work around them.
Related MCP Connectors
Nifty's MCP server β exposes tasks, projects, messages, and files as tools for AI agents.
Run, build, and validate firmware on virtual hardware from your AI agent. Hardware knowledge corpus.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to flash firmware, program memory, modify option bytes, erase chips, reset boards, and capture SWO printf traces for STM32 microcontrollers via STM32CubeCLT.12MIT
- AlicenseAqualityBmaintenanceMCP server that wraps STM32CubeMX CLI to let AI load .ioc projects, modify pin/peripheral configurations, generate HAL code, and export pinout tables.531 PyPI2MIT
- AlicenseAqualityBmaintenanceAn MCP server that enables AI agents to inspect, plan, validate, and apply STM32CubeMX .ioc configuration changes, and generate STM32CubeIDE projects, ensuring safe and testable embedded-system workflows.97MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that lets AI coding agents drive the full STM32 development loopβcode generation, build, flash, debug, serial monitoring, and fault diagnosisβend to end via CubeIDE, CubeMX, CubeProgrammer, OpenOCD, and GDB.1MIT