<p align="center">
  <img src="assets/logo.png" width="480" alt="STM32Cube-MCP Logo" />
  <h1 align="center">STM32Cube-MCP</h1>
  <p align="center">
    <b>The Ultimate Model Context Protocol (MCP) Server for STM32CubeIDE &amp; the STMicroelectronics Ecosystem</b>
  </p>
  <p align="center">
    <i>Full App Control From A to Z: GUI Automation &bull; Headless Compilation &bull; Hardware Flashing &bull; GDB Debugging &bull; Option Bytes &bull; Serial Telemetry &bull; CubeMX .ioc Engineering</i>
  </p>
</p>

<p align="center">
  <a href="https://github.com/brovk2008/STMcube-MCP/actions"><img src="https://img.shields.io/badge/CI-passing-brightgreen?style=for-the-badge&logo=githubactions" alt="CI"></a>
  <a href="https://github.com/brovk2008/STMcube-MCP/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge" alt="License"></a>
  <a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.10%20|%203.11%20|%203.12%20|%203.13%20|%203.14-blue?style=for-the-badge&logo=python" alt="Python"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Protocol%20v2.x-purple?style=for-the-badge" alt="MCP"></a>
  <a href="#cross-platform"><img src="https://img.shields.io/badge/Platform-Windows%20|%20macOS%20|%20Linux-orange?style=for-the-badge" alt="Platform"></a>
  <a href="https://github.com/brovk2008/STMcube-MCP/stargazers"><img src="https://img.shields.io/github/stars/brovk2008/STMcube-MCP?style=for-the-badge&logo=github&color=gold" alt="Stars"></a>
</p>

---

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

```bash
uvx --from git+https://github.com/brovk2008/STMcube-MCP.git stm32cube-mcp
```

### Option 2: Install via `pip`

```bash
git clone https://github.com/brovk2008/STMcube-MCP.git
cd STMcube-MCP
pip install -e .
```

Verify your installation:

```bash
stm32cube-mcp --detect-only
```

Output:
```json
{
  "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`):

```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):

```json
{
  "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](CONTRIBUTING.md) and our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

---

## 📜 License

This project is licensed under the [Apache License 2.0](LICENSE) &copy; 2026 Vaibhav Kumar ([@brovk2008](https://github.com/brovk2008)).