🔌 MCP STM32 Controller Server / MCP STM32 控制器服务器

Control an STM32 microcontroller through the MCP (Model Context Protocol). AI assistants can read/write GPIO, control an LED, read ADC, and drive an OLED — all through natural language.

通过 MCP（Model Context Protocol） 协议控制 STM32 微控制器。AI 助手可以调用本服务提供的工具来读写 STM32 的 GPIO、控制 LED、读取 ADC、操作 OLED 屏幕等。

Architecture

AI Assistant (Claude) ←→ MCP Server (this program) ←→ UART ←→ STM32 firmware

Communication uses a JSON-line protocol: one JSON object per line, terminated by \n.

Related MCP server: Serial MCP Server

Quick Start

1. Install dependencies

pip install -r requirements.txt

2. Connect the hardware

• STM32 USART1: PA9 (TX), PA10 (RX)

• Connect to the PC through a USB-TTL module

• Flash the matching firmware on the device (implement the JSON-line protocol described below)

3. Start the server

# auto-detect the serial port
python main.py

# specify a serial port
python main.py --port COM3

# SSE mode (HTTP service)
python main.py --sse --port COM3

Tools

Resources

Configuration

Via environment variables or command-line arguments:

Integrate with Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "stm32": {
      "command": "python",
      "args": ["C:/path/to/mcp-stm32-server/main.py", "--port", "COM3"],
      "env": {}
    }
  }
}

Wire Protocol (JSON-lines)

Each line is an independent JSON object. The firmware simply echoes a response with the matching id.

Request:

{"id":1,"cmd":"set_led","args":{"brightness":75}}

Success response:

{"id":1,"status":"ok","data":{"brightness":75}}

Error response:

{"id":1,"status":"error","msg":"brightness must be 0-100"}

Firmware contract: on every received request, reply with one JSON line carrying the same id, plus status ("ok" / "error") and either data or msg. Boot-log lines that are not valid JSON are skipped by the client automatically.

License

MIT License.

架构

AI 助手 (Claude) ←→ MCP Server (本程序) ←→ 串口 ←→ STM32 固件

通信使用 JSON 行协议，每行一个 JSON 对象，以 \n 结尾。

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 连接硬件

• STM32 的 USART1：PA9(TX)，PA10(RX)

• 通过 USB-TTL 模块连接电脑

• 在设备端烧录实现下述 JSON 行协议的配套固件

3. 启动服务

# 自动检测串口
python main.py

# 指定串口
python main.py --port COM3

# SSE 模式（HTTP 服务）
python main.py --sse --port COM3

工具列表

资源

配置

通过环境变量或命令行参数：

与 Claude Desktop 集成

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "stm32": {
      "command": "python",
      "args": ["C:/path/to/mcp-stm32-server/main.py", "--port", "COM3"],
      "env": {}
    }
  }
}

协议格式（JSON 行）

每一行是一个独立的 JSON 对象。固件只需回一个 id 相同的 JSON 行即可。

请求：

{"id":1,"cmd":"set_led","args":{"brightness":75}}

成功响应：

{"id":1,"status":"ok","data":{"brightness":75}}

错误响应：

{"id":1,"status":"error","msg":"brightness must be 0-100"}

固件约定：收到每条请求后，回一行包含相同 id 的 JSON，含 status（"ok" / "error"）以及 data 或 msg。启动时的非 JSON 日志行会被客户端自动跳过。

许可证

MIT License。