embedded-mcp

Let an AI assistant read, command, and debug your microcontroller — over plain serial.

embedded-mcp is a Model Context Protocol server. It gives an MCP-capable client (Claude Desktop, Claude Code, …) a small set of tools to talk to a real board over a serial port.

When you debug firmware, your AI pair can now see what the board prints and poke it back — instead of you copy-pasting the serial monitor by hand.

┌─────────────┐      MCP (stdio)      ┌───────────────┐     UART / USB-serial    ┌──────────────┐
│  AI client  │  ◄────────────────►   │  embedded-mcp │  ◄────────────────────►  │  your board  │
│  (Claude)   │                       │   (this repo) │       (pyserial)         │  STM32 / ...  │
└─────────────┘                       └───────────────┘                          └──────────────┘

Why

Embedded debugging is a loop of flash → watch the serial monitor → send a command → read the dump → decode a register against the datasheet. That loop is exactly the kind of tedious, context-heavy work an AI is good at — if you give it eyes and hands on the hardware. This server is those eyes and hands.

Related MCP server: Serial MCP Server

Tools

Install

git clone https://github.com/atillab1/embedded-mcp.git
cd embedded-mcp
pip install -e .

Use with Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "embedded-mcp": {
      "command": "embedded-mcp"
    }
  }
}

Restart Claude Desktop. Then just ask:

"List my serial ports, then read whatever COM5 is printing at 115200 for 5 seconds."

"Send status to the board on COM5 and tell me what it replies."

"Register RCC->CR read back as 0x4002. Decode it: bit 0 is HSION, bit 17 is HSEON, bit 25 is PLLRDY."

Example: decode a register

decode_register(value=0x4002, fields=[{"name":"HSION","bit":0},{"name":"HSEON","bit":17}], width=32)

{
  "value": 16386,
  "hex": "0x00004002",
  "binary": "00000000000000000100000000000010",
  "fields": [
    { "name": "HSION", "bits": "[0]",  "value": 0 },
    { "name": "HSEON", "bits": "[17]", "value": 0 }
  ]
}

Try it now (no hardware needed)

The register decoders work entirely offline — give them a quick spin:

python examples/demo.py

Flashing

flash_firmware shells out to a real flasher and is dry-run by default — it returns the exact command it would run, so you can review it before anything touches your board:

"Dry-run flashing build/app.bin to my STM32 with st-flash."

Flip dry_run=False to actually flash. Supported: st-flash (.bin), probe-rs (.elf, needs chip), openocd (.elf, needs openocd_target).

Safety notes

• Tools open the port only for the duration of the call, then close it — they do not hold the port, so your normal IDE serial monitor can share it (one at a time).

• Read durations are capped at 30s so a call can never hang the client.

• flash_firmware is destructive; it defaults to a dry run and never flashes unless you explicitly pass dry_run=False.

• This talks to whatever board is on the port. Don't point it at something you don't own.

Roadmap

• Unit tests + GitHub Actions CI

• Load a register map from an SVD file (decode_register_svd)

• Flashing hook (flash_firmware via st-flash / probe-rs / openocd)

• Streaming/continuous monitor (notifications instead of fixed windows)

• SVD auto-discovery from the connected chip id

Contributions welcome — open an issue or PR.

Development

pip install -e .
pip install pytest
pytest -q

License

MIT © Atilla — see LICENSE.