STMcube-MCP

Mcp server specially built of STMcube IDE

Comment

STM32Cube-MCP Logo

STM32Cube-MCP

The Ultimate Model Context Protocol (MCP) Server for STM32CubeIDE & the STMicroelectronics Ecosystem

Full App Control From A to Z: GUI Automation • Headless Compilation • Hardware Flashing • GDB Debugging • Option Bytes • Serial Telemetry • CubeMX .ioc Engineering

CI License Python MCP Platform Stars

⚡ 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:

  1. 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.
  2. Headless Build Engine: Compile, clean, and re-index projects headlessly via headless-build and stm32cubeidec, then parse exact Flash and RAM memory footprints (arm-none-eabi-size).
  3. 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.
  4. Deep Silicon Inspection: Read and write 32-bit registers/memory addresses live, configure hardware option bytes (RDP, BOR, Watchdog), and dump flash firmware.
  5. GDB Server & Remote Debugging: Spin up ST-LINK_gdbserver or openocd on demand, attach arm-none-eabi-gdb, halt cores, inspect registers, evaluate backtraces, and set breakpoints.
  6. Live Hardware Telemetry (UART): Stream printf logs and FreeRTOS telemetry directly to the agent over serial COM ports.
  7. CubeMX .ioc Engineering: Parse, scaffold, and mutate STM32CubeMX .ioc pinout definitions, clock trees, and peripheral drivers programmatically.

🏗️ 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 (Ctrl+B, F11, F5, F6, F8), capture window screenshots in base64 PNG.
⚙️ Headless Compilation Run automated headless builds via headless-build.bat / .sh with error/warning parsing and zero Eclipse GUI overhead.
📊 Memory Footprint Analyze .elf and .map files using arm-none-eabi-size with exact breakdowns of Text, Data, BSS, Flash %, and RAM %.
🔌 Probe Discovery Auto-detect connected ST-LINK v2/v3 probes with hardware serial numbers, DFU bootloader devices, and COM ports.
⚡ Hardware Flashing Flash .elf, .hex, or .bin with instant readback verification, start execution, and software/hardware NRST reset.
🔬 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 ST-LINK_gdbserver / openocd lifecycle management, batch GDB command evaluation, register dumps, and backtraces.
📡 Serial UART Monitor Bidirectional COM port / UART monitor to read MCU printf streams and send commands.
📁 CubeMX .ioc Engine Programmatically inspect and modify .ioc pin mappings, clocks, and peripheral configurations.
🧩 Project Scaffolder Scaffold ready-to-build STM32 projects (.project, .cproject, .ioc, main.c, main.h, linker script, and Makefile).
🌐 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-mcp

Option 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-only

Output:

{
  "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: stm32cube
  • Command: python
  • Args: ["-m", "stm32_mcp"]

🧰 Complete Tool Catalog (34 Tools)

1. Toolchain & Probe Discovery

Tool Description
stm32_detect_installation Auto-detects IDE installation, version, and all bundled CLI/GDB/GCC tools.
stm32_get_system_status Returns IDE running status, PIDs, memory usage, open windows, and active probes.
stm32_list_connected_probes Discovers ST-LINK probes (with SNs), DFU devices, J-Link, and serial ports.
stm32_get_target_info Queries target MCU silicon for Device ID, Device Name, and Flash size.

2. IDE Lifecycle & GUI Automation

Tool Description
stm32_launch_ide Opens STM32CubeIDE GUI with optional workspace, project, or file path.
stm32_close_ide Closes running IDE instances gracefully or forcefully.
stm32_focus_ide_window Brings the STM32CubeIDE window to the foreground.
stm32_get_ide_windows Lists all open IDE windows, dialogs, titles, and screen coordinates.
stm32_send_ide_shortcut Sends keyboard shortcuts (build, debug, run, step_into, step_over, resume, terminate, save_all, open_resource).
stm32_capture_ide_screenshot Captures high-res screenshot of IDE window or desktop as base64 PNG.

3. Project & CubeMX Workspace Management

Tool Description
stm32_list_projects Discovers all STM32 projects in a directory with target MCU and .ioc status.
stm32_create_project Scaffolds complete STM32 project (.project, .cproject, .ioc, main.c, main.h, linker, Makefile).
stm32_import_project Imports a project into the headless Eclipse workspace.
stm32_remove_project Removes a project from the headless workspace.
stm32_parse_ioc Extracts MCU family, CPU type, clock frequency, pinouts, and enabled IPs from .ioc.
stm32_update_ioc Updates or adds configuration parameters in a CubeMX .ioc file.

4. Headless Compilation & Memory Analysis

Tool Description
stm32_build_project Triggers headless build (Debug / Release) with error/warning analysis.
stm32_clean_project Performs clean build on project or workspace.
stm32_get_build_artifacts Locates .elf, .hex, .bin, .map, and calculates Flash & RAM usage with arm-none-eabi-size.

5. Flashing, Erasing & Memory Control

Tool Description
stm32_flash_firmware Flashes firmware with readback verification and auto-reset.
stm32_erase_flash Performs chip mass erase or sector erase.
stm32_reset_target Triggers software or hardware NRST pin reset.
stm32_read_memory Reads 32-bit words from registers, RAM, or Flash.
stm32_write_memory Writes 32-bit values directly to memory or hardware registers.
stm32_read_option_bytes Dumps hardware option bytes (RDP, BOR, WDG, Boot).
stm32_write_option_bytes Modifies device option bytes.
stm32_dump_flash_to_file Dumps firmware from target MCU into a local file.

6. Debugging & GDB Server

Tool Description
stm32_start_gdb_server Starts background ST-LINK_gdbserver on TCP port (default 61234).
stm32_start_openocd Launches OpenOCD with target/interface scripts.
stm32_stop_gdb_server Terminates active GDB server processes.
stm32_run_gdb_script Executes automated batch GDB session (registers, backtrace, breakpoints).

7. Serial Telemetry & UART

Tool Description
stm32_list_serial_ports Lists all available COM / UART ports with hardware IDs.
stm32_read_serial Captures incoming UART telemetry / printf logs.
stm32_write_serial 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, and STM32_Programmer_CLI.
  • macOS: Auto-detects /Applications/STM32CubeIDE.app, AppleScript UI activation, and standard Homebrew / ST toolchains.
  • Linux: Auto-detects /opt/st/stm32cubeide, wmctrl/xdotool window 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).

Built With

Share this project:

Updates