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

Controla un microcontrolador STM32 mediante el MCP (Model Context Protocol). Los asistentes de IA pueden leer/escribir GPIO, controlar un LED, leer un valor ADC y manejar una pantalla OLED, todo mediante lenguaje natural.

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

Arquitectura

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

La comunicación utiliza un protocolo de líneas JSON: un objeto JSON por línea, terminado con \n.

Inicio rápido

1. Instala las dependencias

pip install -r requirements.txt

2. Conecta el hardware

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

• Conecta al PC mediante un módulo USB-TTL

• Graba el firmware correspondiente en el dispositivo (implementa el protocolo de líneas JSON que se describe a continuación)

3. Inicia el servidor

# 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

Herramientas

Recursos

Configuración

Mediante variables de entorno o argumentos de línea de comandos:

Integración con Claude Desktop

Edita claude_desktop_config.json:

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

Protocolo de comunicación (JSON-lines)

Cada línea es un objeto JSON independiente. El firmware solo tiene que responder con un objeto JSON que tenga el mismo id.

Solicitud:

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

Respuesta correcta:

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

Respuesta de error:

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

Contrato del firmware: tras cada solicitud recibida, responde con una línea JSON que lleve el mismo id, junto con status ("ok" / "error") y data o msg. Las líneas del registro de arranque que no sean JSON válido se omiten automáticamente por el cliente.

Licencia

Licencia MIT.

架构

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。