🔌 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 屏幕等。

---

<!-- ═══════════════════════════════════════════════════════════════ --> <!-- English --> <!-- ═══════════════════════════════════════════════════════════════ -->

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.

---

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

Tool	Description	Arguments
ping	check whether the STM32 is online	—
set_led	set the LED brightness	brightness: 0-100
get_led	read the current LED brightness	—
read_pin	read a GPIO level	pin: "PA0", "PC13", ...
write_pin	set a GPIO level	pin + value: 0/1
read_adc	read an ADC value	channel: 0-2
oled_clear	clear the OLED screen	—
oled_print	print text on the OLED	x + y + text

Resources

URI	Description
stm32://status	connection status, port info, uptime

---

Configuration

Via environment variables or command-line arguments:

Argument	Env var	Default	Description
--port	STM32_PORT	auto-detect	serial port
--baud	—	115200	baud rate
--sse	—	false	SSE mode
--sse-port	—	8000	SSE port

---

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

---

工具列表

工具	说明	参数
ping	检测 STM32 在线状态	无
set_led	设置 LED 亮度	brightness: 0-100
get_led	读取 LED 亮度	无
read_pin	读取 GPIO 电平	pin: "PA0", "PC13" 等
write_pin	设置 GPIO 电平	pin + value: 0/1
read_adc	读取 ADC 值	channel: 0-2
oled_clear	清空 OLED 屏幕	无
oled_print	在 OLED 上显示文字	x + y + text

资源

URI	说明
stm32://status	连接状态、串口信息、运行时间

---

配置

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

参数	环境变量	默认值	说明
--port	STM32_PORT	自动检测	串口号
--baud	-	115200	波特率
--sse	-	false	SSE 模式
--sse-port	-	8000	SSE 端口

---

与 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。