STM32 Model Context Protocol (MCP) Server

An open-source Model Context Protocol (MCP) server that drives the official STMicroelectronics STM32 toolchain from the command line. Designed specifically for AI coding assistants—including Claude Code and Google Antigravity—enabling autonomous, reliable, and headless embedded firmware development.

Key Features

• 100% Headless Operation: Never launches or drives a GUI. Interacts exclusively via:

  • STM32CubeMX script mode (config load, project generate, exit)

  • stm32cubeidec.exe Eclipse CDT headless builder

  • STM32_Programmer_CLI.exe for hardware flashing and verification

  • arm-none-eabi-gcc and arm-none-eabi-size for compilation and memory analysis

• Structured Compiler Diagnostics: Parses GCC outputs into typed error/warning/note objects with precise file, line, and column coordinates. Never floods context windows with megabytes of unparsed build logs.

• Safety Gates: Destructive actions (stm32_clean and stm32_flash) require explicit confirmation (confirm: true), preventing accidental code loss or unwanted board programming.

• Strict User-Code Boundaries: stm32_patch_user_code enforces paired, non-nested, uncorrupted /* USER CODE BEGIN */ and /* USER CODE END */ blocks, ensuring CubeMX regeneration never erases user logic.

• Zero Credential Handling: Does not handle or store ST logins or scrape downloads. If a target MCU firmware package is missing, the tool returns a clear, actionable message directing the developer to download it manually from st.com.

• Enforced ASCII Path Validation: ST's legacy CLI tools fail abruptly on Windows paths containing Cyrillic, spaces, or Unicode characters. This server intercepts and rejects non-ASCII paths immediately with diagnostic guidance before invoking external tools.

Related MCP server: stm32-mcp

Supported Environments

• Operating Systems: Windows 10/11, macOS, Linux

• AI Clients:

  • Claude Code (.claude-plugin/plugin.json)

  • Google Antigravity (antigravity/mcp_config.json)

  • Any MCP-compliant client (Cursor, Zed, etc.)

Tool Reference

The MCP server exposes 9 dedicated tools covering the entire embedded development lifecycle:

Installation & Setup

Prerequisites

1. Node.js: >= 20.0.0

2. STM32CubeIDE: Recommended version 1.15.0 to 1.19.0 (installed at default path C:\ST\STM32CubeIDE_* or /opt/st/stm32cubeide).

3. STM32Cube MCU Packages: Download desired target families (e.g. STM32Cube_FW_F1_V1.8.6) from st.com and extract into ~/STM32Cube/Repository.

Build from Source

git clone https://github.com/irrumi/stm32-mcp.git
cd stm32-mcp
npm install
npm run build
npm test

AI Client Configuration

Claude Code

Add the plugin manifest to your project or Claude Code configuration:

{
  "mcpServers": {
    "stm32": {
      "command": "node",
      "args": ["<PATH_TO_PLUGIN>/dist/index.js"]
    }
  }
}

Google Antigravity

Reference the included antigravity/mcp_config.json:

{
  "mcpServers": {
    "stm32": {
      "command": "node",
      "args": ["C:/path/to/stm32-mcp/dist/index.js"]
    }
  }
}

Load the skills/stm32-firmware/SKILL.md skill into your Antigravity skills repository:

# Windows PowerShell
Copy-Item -Recurse -Path ".\skills\stm32-firmware" -Destination "$HOME\.gemini\antigravity\skills\"

Worked Walkthrough: Blinky on STM32F103 (Blue Pill)

1. Verify Environment

// Prompt: "Check STM32 toolchain health"
// Tool called: stm32_doctor
{}

Response: Reports paths to stm32cubeidec.exe, STM32CubeMX.jar, STM32_Programmer_CLI.exe, arm-none-eabi-gcc, and confirms STM32Cube_FW_F1 package is present.

2. Create Project

// Prompt: "Create a new STM32F103C8 project called blinky-f103"
// Tool called: stm32_create_project
{
  "name": "blinky-f103",
  "mcu": "STM32F103C8Tx",
  "path": "C:/projects/stm32/blinky-f103",
  "debug": "swd"
}

3. Assign Pin Configurations

// Prompt: "Configure PC13 as an output for the onboard LED"
// Tool called: stm32_configure_pins
{
  "iocPath": "C:/projects/stm32/blinky-f103/blinky-f103.ioc",
  "pins": [
    { "pin": "PC13", "mode": "GPIO_Output", "label": "LED_STATUS" }
  ]
}

4. Headless Code Generation

// Prompt: "Generate HAL code with CubeMX"
// Tool called: stm32_generate_code
{
  "projectDir": "C:/projects/stm32/blinky-f103"
}

5. Insert Application Code

// Prompt: "Add non-blocking blink logic using HAL_GetTick() inside while loop"
// Tool called: stm32_patch_user_code
{
  "filePath": "C:/projects/stm32/blinky-f103/Core/Src/main.c",
  "marker": "WHILE",
  "mode": "replace",
  "content": "    static uint32_t last_tick = 0;\n    if (HAL_GetTick() - last_tick >= 500) {\n      last_tick = HAL_GetTick();\n      HAL_GPIO_TogglePin(GPIOC, GPIO_PIN_13);\n    }"
}

6. Headless Compilation & Memory Analysis

// Prompt: "Build the Debug configuration"
// Tool called: stm32_build
{
  "projectDir": "C:/projects/stm32/blinky-f103",
  "configuration": "Debug"
}

Structured Output:

{
  "success": true,
  "summary": "Build finished successfully with 0 errors and 0 warnings.",
  "diagnostics": [],
  "memoryUsage": {
    "flashBytes": 3844,
    "ramBytes": 1580,
    "text": 3824,
    "data": 20,
    "bss": 1560
  }
}

7. Program Target Hardware

// Prompt: "Flash the firmware to my connected Blue Pill"
// Tool called: stm32_flash
{
  "projectDir": "C:/projects/stm32/blinky-f103",
  "verify": true,
  "reset": true,
  "confirm": true
}

Architecture & Security Considerations

• Process Execution: All external commands are executed using child_process.spawn with explicit argument arrays and shell: false. Shell interpolation is strictly prohibited.

• Path Sanitization: All incoming file and directory paths are validated against ASCII character sets before any filesystem or process operation.

• Non-Destructive Regeneration: Code injection checks BEGIN/END balance, marker matching, duplicate detection, and nesting protection.

License

MIT © irrumi