STM32CubeMX MCP

stm32cubemx-mcp is a local Model Context Protocol (MCP) server. It helps artificial intelligence (AI) agents turn structured embedded-system requirements into safe, testable STM32CubeMX workflows.

Project documentation and user-facing text use ASD-STE100 Technical English.

The agent analyzes microcontroller unit (MCU) datasheets, schematics, board photos, and user requirements. The server supplies the deterministic execution layer. It inspects the local toolchain and STM32CubeMX IOC files. It validates paths and configuration state. It also controls CubeMX validation and project generation.

What you can do now

Use the Codex plugin to complete these workflows:

The server does not edit arbitrary C or C++ application code. It does not compile, flash, or debug a project.

Related MCP server: Swarm Orchestrator

Quick start with Codex

Install the server and plugin. Then start a new Codex task from the embedded project directory. Give Codex the applicable datasheet, schematic, board image, IOC file, and requirements.

Create a new IOC file and STM32CubeIDE project

Use the installed STM32CubeMX plugin. Create an IOC file for NUCLEO-F401RE.
Configure USART2 on PA2 and PA3 for 115200 bit/s. Preserve the Serial Wire
Debug pins. Show the planned configuration before you apply it. After approval,
generate a new STM32CubeIDE project in a new output directory. Do not compile
or flash the project.

Edit an existing IOC file

Use the installed STM32CubeMX plugin. Inspect board.ioc. Plan a change that
configures PA5 as a labeled GPIO output and preserves PA13 and PA14 for Serial
Wire Debug. Show the changed IOC keys, text difference, diagnostics, and source
SHA-256 hash. Do not apply the plan until I approve it.

Generate from an existing IOC file

Use the installed STM32CubeMX plugin. Validate board.ioc. Generate a new
STM32CubeIDE project in generated/board-app. Report output_directory,
project_path, the source hash, generated-file count, and diagnostics. Do not
modify board.ioc. Do not compile the project.

The agent uses this safe sequence for an IOC edit:

inspect -> plan -> show difference and source hash -> get approval
        -> validate staged IOC -> create backup -> replace IOC
        -> generate a new project when requested

Planned capabilities

• Generate a CMake project from an IOC file.

• Configure and build a generated CMake project.

• Build an STM32CubeIDE project with the headless interface.

• List debug probes and plan a flash operation with STM32CubeProgrammer.

• Flash only after a separate explicit approval.

Current MCP tools

Intended workflow

flowchart LR
    A["User inputs: requirements, datasheets, schematics"] --> B["AI agent: hardware intent"]
    B --> C["MCP: inspect and resolve constraints"]
    C --> D["MCP: plan and preview IOC changes"]
    D --> E["MCP: transactional apply"]
    E --> F["CubeMX CLI: validate and generate"]
    F --> G["New STM32CubeIDE project"]
    G --> H["Structured diagnostics for the agent"]
    H -.-> I["Planned: CubeIDE or CMake build"]

The supported CubeMX command-line interface (CLI) loads MCUs, boards, and IOC configurations. CubeMX can generate STM32CubeIDE or CMake projects. The current MCP generation tool supports STM32CubeIDE only. It does not expose the complete pin and peripheral editor as a command API. For that reason, this project treats IOC changes as version-aware transactions and uses CubeMX as the validation and generation authority.

See Architecture for the safety model and planned tool contract. See the first-principles study guide to rebuild the main MCP layers in a separate learning project.

Codex plugin

This repository is an unofficial Codex plugin marketplace. The plugin contains the Codex workflow guidance and the MCP server configuration. The Python package contains the executable MCP server.

Install on Windows

Install the Codex CLI if codex.cmd --version does not work:

npm.cmd install --global @openai/codex

Install pipx if py -m pipx --version does not work:

py -m pip install --user pipx
py -m pipx ensurepath

Install the Python MCP server:

py -m pipx install git+https://github.com/Wafleem/stm32cubemx_mcp.git

The Windows plugin first searches the Codex process PATH. If the command is not on that PATH, the plugin uses the default pipx application path at %USERPROFILE%\.local\bin\stm32cubemx-mcp.exe. This fallback lets the Codex desktop app start the server after pipx changes the user PATH.

Add the marketplace and install the plugin:

codex.cmd plugin marketplace add Wafleem/stm32cubemx_mcp
codex.cmd plugin add stm32cubemx-mcp@wafleem-stm32

Close Codex after the installation. Open Codex again and start a new task. Use /mcp to confirm that the stm32cubemx server is connected. The plugin source is in plugins/stm32cubemx-mcp.

Verify the installation

Run these checks in a new PowerShell window:

Get-Command stm32cubemx-mcp
py -m pipx list
codex.cmd --version
codex.cmd plugin list

The stm32cubemx-mcp command starts a standard-input MCP server. It waits for MCP messages. This wait is correct. Press Ctrl+C if you start the server manually. Do not use a manual server start as the connection test.

Use this prompt in a new Codex task for a read-only connection test:

Use the installed STM32CubeMX plugin. Call cubemx_environment. Do not modify
files. Report the CubeMX path, Java path, operating system, allowed roots, and
diagnostics.

Update the installation

Update the Python server when a runtime release is available:

py -m pipx upgrade stm32cubemx-mcp

Refresh the marketplace and reinstall the current plugin version:

codex.cmd plugin marketplace upgrade wafleem-stm32
codex.cmd plugin add stm32cubemx-mcp@wafleem-stm32

Close Codex and start a new task after the update.

Usage guide

1. Give the technical evidence to the agent

Attach the datasheet, schematic, board image, IOC file, and project files to the Codex task as applicable. State the MCU part number and package. State the required peripheral, signal, data rate, clock, and pin restrictions.

Codex analyzes this evidence. The MCP server does not read or interpret the datasheet or schematic by itself. Codex converts the result of its analysis into structured MCP tool calls.

Example request:

This project uses an STM32F401RE on a NUCLEO-F401RE. Configure USART2 for
115200 bit/s on PA2 and PA3. Preserve the Serial Wire Debug (SWD) pins. Inspect
and plan the change. Do not modify the IOC file until I approve the plan.

2. Create or inspect the IOC file

Codex first calls cubemx_environment. It confirms the CubeMX path and the allowed roots.

For a new project, Codex can call cubemx_create_ioc. The call selects one known board or microcontroller unit (MCU). It selects the project name, toolchain, and a new output directory. The server uses typed CubeMX commands. It validates the new IOC file before it makes the output directory available.

For an existing project, Codex can call cubemx_list_ioc if the IOC path is not known. It then calls cubemx_inspect_ioc to read the current project state.

The inspection result includes the source SHA-256 hash. This hash identifies the exact IOC content that Codex inspected.

3. Create and review a change plan

Codex calls cubemx_plan_ioc_changes. This tool returns:

• a plan identifier;

• the source and planned SHA-256 hashes;

• a list of changed IOC keys;

• a unified text difference;

• diagnostics.

This call does not write the IOC file. Review the pin assignments, peripheral names, parameter values, project name, and toolchain. Give approval only for the displayed plan.

4. Apply an approved IOC plan

After approval, Codex calls cubemx_apply_ioc_changes with the same plan request and the approved source hash. The server creates the plan again. It stops if the source hash changed.

By default, the server validates the planned IOC content with CubeMX before it writes the source file. It then creates a hash-named backup and uses one atomic replacement operation. It restores the backup if the applied hash is not equal to the approved planned hash.

Do not disable CubeMX validation for normal use. The validation bypass requires both an explicit request value and the CUBEMX_MCP_ALLOW_UNVALIDATED_APPLY=true server setting.

5. Generate or preview a project

Use cubemx_generate_project for a new STM32CubeIDE project. The output directory must not exist. The tool validates the IOC file, generates into a temporary directory, and then checks the complete CubeIDE output. The check resolves each linked resource in the Eclipse .project file. It also requires main.c, main.h, a CMSIS core header, and a Hardware Abstraction Layer (HAL) source file. The tool moves the complete output container to the requested path only after these checks pass.

The tool sets the staged IOC project name and filename to the requested project name. It selects the current CubeMX toolchain key when that key is available. It also requests a project below one root directory. These staged changes do not change the source IOC file.

CubeMX can change the internal project name and filename when validation saves a temporary roundtrip.ioc file. The round-trip check permits these two temporary identity changes. The generated-project check still requires the requested IOC filename and internal project identity.

The output_directory result identifies the complete generated container. The project_path result identifies the Eclipse project root. These paths are usually equal. They can be different when CubeMX creates nested Eclipse metadata.

Use cubemx_plan_regeneration for an existing STM32CubeIDE project. This tool copies the project before validation. It validates the IOC file in an isolated temporary directory. It then regenerates the copy and reports added, modified, and deleted files. It checks the source project after each phase. It does not change the source project.

The preview stages the project below a temporary generation parent. It passes that parent to CubeMX. This layout prevents CubeMX from creating a second nested copy of the project.

The current server does not apply an existing-project regeneration plan. It also does not compile a project. Treat IOC validation, project generation, and compilation as different results.

6. Use allowed roots

All input and output paths must be below an allowed root. If CUBEMX_MCP_ALLOWED_ROOTS is not set, the server permits only its current working directory. On Windows, separate multiple roots with a semicolon.

Example:

$env:CUBEMX_MCP_ALLOWED_ROOTS = "C:\work\board-a;D:\shared\firmware"

This command applies to Codex processes that start from the same PowerShell session. For the desktop app, set the variable in the Windows user environment and then restart the app. Use cubemx_environment to confirm the effective roots.

MCP API and tool-call overview

The server uses MCP over standard input and standard output. It does not expose an HTTP API. Codex and other MCP clients create the JSON-RPC messages. Most users must use natural-language prompts instead of writing JSON-RPC messages.

All tool results use structured JSON. Diagnostics contain severity, code, message, and an optional IOC line number.

CubeMX process results contain the exit code, duration, timeout state, and captured output. Successful results contain only a short output tail. Failed results keep a larger bounded output for diagnosis. Nonfatal Java preferences output uses the cubemx.java_preferences_warning diagnostic code.

Read-only calls

cubemx_environment

Arguments:

{}

Main result fields: operating_system, architecture, python_version, python_executable, cubemx, cubeide, cmake, ninja, allowed_roots, and diagnostics.

cubemx_list_ioc

Arguments:

{
  "root": ".",
  "recursive": true,
  "limit": 100
}

root defaults to the current directory. recursive defaults to true. limit defaults to 100. The result contains root, files, and truncated.

cubemx_inspect_ioc

Arguments:

{
  "path": "board.ioc"
}

The result contains summary and diagnostics. The summary contains MCU, board, project, toolchain, CubeMX version, peripheral, pin, clock, file size, and source-hash data.

cubemx_validate_ioc

Arguments:

{
  "path": "board.ioc"
}

The result contains valid, source and round-trip hashes, the CubeMX process result, and diagnostics. The source IOC file remains unchanged.

IOC creation, plan, and apply calls

cubemx_create_ioc

The tool has one request argument:

{
  "request": {
    "target_kind": "board",
    "target": "NUCLEO-F401RE",
    "output_directory": "projects/f401-base",
    "project_name": "f401_base",
    "board_mode": "allmodes",
    "toolchain": "STM32CubeIDE"
  }
}

Set target_kind to board or mcu. Use the exact CubeMX board or MCU identifier in target. board_mode can be allmodes or nomode. The toolchain can be STM32CubeIDE or CMake. The output directory must not exist.

The result contains the IOC path, project path, target, toolchain, source hash, validation result, CubeMX process result, and diagnostics. The server removes the staged directory if creation or validation fails.

cubemx_plan_ioc_changes

The tool has one request argument:

{
  "request": {
    "path": "board.ioc",
    "pin_assignments": [
      {
        "pin": "PA2",
        "signal": "USART2_TX",
        "label": "DEBUG_TX",
        "locked": true
      },
      {
        "pin": "PA3",
        "signal": "USART2_RX",
        "label": "DEBUG_RX",
        "locked": true
      }
    ],
    "enabled_peripherals": ["USART2"],
    "parameter_updates": {},
    "project_name": null,
    "toolchain": "STM32CubeIDE",
    "allow_debug_pin_change": false
  }
}

Use exact CubeMX IOC keys in parameter_updates. Do not guess these keys. Use pin_assignments for pin signals, labels, and lock states. The server rejects these pin properties in parameter_updates. toolchain can be STM32CubeIDE, CMake, or null. Debug-pin changes are blocked unless allow_debug_pin_change is true.

The result contains plan_id, source_sha256, planned_sha256, changes, unified_diff, validation_status, and diagnostics.

cubemx_apply_ioc_changes

The tool has one request argument. plan_request must be equal to the approved planning request:

{
  "request": {
    "plan_request": {
      "path": "board.ioc",
      "pin_assignments": [
        {
          "pin": "PA2",
          "signal": "USART2_TX",
          "label": "DEBUG_TX",
          "locked": true
        },
        {
          "pin": "PA3",
          "signal": "USART2_RX",
          "label": "DEBUG_RX",
          "locked": true
        }
      ],
      "enabled_peripherals": ["USART2"],
      "parameter_updates": {},
      "project_name": null,
      "toolchain": "STM32CubeIDE",
      "allow_debug_pin_change": false
    },
    "expected_source_sha256": "<64-character hash from the approved plan>",
    "skip_cubemx_validation": false
  }
}

The result contains the plan identifier, source and applied hashes, backup path, change state, CubeMX validation state, and changed IOC keys.

Project calls

cubemx_generate_project

The tool has one request argument:

{
  "request": {
    "ioc_path": "board.ioc",
    "output_directory": "generated/blinky",
    "project_name": "blinky",
    "toolchain": "STM32CubeIDE"
  }
}

The current generation tool supports only STM32CubeIDE. The project name can contain letters, numbers, _, ., and -. It can contain 1 to 80 characters. The source IOC file remains unchanged. The result contains succeeded, output_directory, project_path, project_name, toolchain, source_sha256, the validation result, the CubeMX process result, the generated-file list, and diagnostics. output_directory identifies the complete output container. project_path identifies the Eclipse project root.

cubemx_plan_regeneration

The tool has one request argument:

{
  "request": {
    "project_directory": "existing-project",
    "ioc_path": null
  }
}

Set ioc_path when the project contains more than one IOC file. A relative IOC path is relative to project_directory. The result contains source and planned project-manifest hashes, file changes, IOC validation, the CubeMX process result, and diagnostics. Check succeeded before you use plan_id or planned_manifest_sha256. These fields can be null when a safe preview does not complete. A source-change diagnostic identifies each detected path.

JSON-RPC call form

An MCP client sends a tool call in this form:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "cubemx_inspect_ioc",
    "arguments": {
      "path": "board.ioc"
    }
  }
}

The MCP client performs protocol initialization before it sends this call. Application code should use an MCP SDK instead of writing protocol messages directly.

Requirements

• Python 3.11 or newer

• STM32CubeMX for generation and validation features

• STM32CubeIDE for current project-generation workflows

• A CMake Arm toolchain when planned CMake generation and build support is available

Windows is the first development platform. macOS on Apple silicon is a target platform and is represented in the platform abstraction and CI matrix. The current Codex plugin launcher supports Windows. macOS users must configure the MCP executable path manually until the macOS plugin launcher is available.

Development setup

py -3.11 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
pytest

On macOS:

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
pytest

Run the stdio server with:

stm32cubemx-mcp

MCP hosts should launch the server using an absolute Python or executable path. Nothing except MCP protocol messages may be written to stdout; application logs go to stderr.

Configuration

When CUBEMX_MCP_ALLOWED_ROOTS is unset, access is restricted to the process's current working directory. This default is deliberately narrow.

References

• STM32CubeMX 6.18 command-line documentation

• Official MCP Python SDK

License

MIT