serial-mcp

MCP server that lets LLMs talk to serial devices: microcontrollers, routers, modems, embedded Linux, anything with a UART.

Why this exists

LLMs are surprisingly good at interacting with hardware over serial, but without proper tooling they resort to hacking together Python scripts or asking you to copy-paste between terminals. This MCP server gives them a real serial interface instead.

What makes this different from the other serial MCP servers? I actually use this. Every tool exists because I hit a wall without it, not because it sounded good on a feature list. It handles things the others don't: XMODEM file transfers, hardware signal control for reset/bootloader sequences, baud rate detection, triggered responses for catching time-sensitive boot prompts, and a ring buffer that doesn't lose data between tool calls.

Install

With uv (recommended)

Install globally so the serial-mcp command is available everywhere:

uv tool install serial-mcp

Or from a local clone:

uv tool install /path/to/serial-mcp

With pip

pip install serial-mcp

From source (editable)

git clone https://github.com/alxgmpr/serial-mcp.git
cd serial-mcp
uv pip install -e .

Update

uv tool upgrade serial-mcp

Or with pip: pip install --upgrade serial-mcp

Configure

Claude Code

claude mcp add serial-mcp -- serial-mcp

That's it. Verify with claude mcp list.

If you installed from source instead of globally, use the full path:

claude mcp add serial-mcp -- python3 -m serial_mcp.server

Claude Desktop (claude_desktop_config.json)

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

With uvx (no install)

{
  "mcpServers": {
    "serial": {
      "command": "uvx",
      "args": ["serial-mcp"]
    }
  }
}

Tool profiles

The default full profile exposes all tools. Use core when your client loads every schema and you only need the common text workflow:

serial-mcp --profile core

The core profile exposes list_serial_ports, serial_open, serial_close, serial_execute, serial_command, serial_detect_baud, and serial_status. You can also set SERIAL_MCP_TOOL_PROFILE=core in the server environment.

Tools

Tools use the serial_ prefix to avoid collisions, except for the discovery entry point list_serial_ports.

serial_wait_for and serial_command both support triggered responses: you can set respond or respond_hex so the server automatically transmits a reply the instant a pattern matches. This is useful for catching time-sensitive prompts like U-Boot's "Hit any key to stop autoboot" where the MCP round-trip would be too slow.

Text commands and reads return at most 16 KiB by default; hex reads use the same raw-byte limit. Set max_output_bytes per call when needed. When output is larger, the tools retain the newest bytes and report truncated, returned_bytes, and omitted_bytes; byte_count remains the total serial bytes captured.

The reader thread pauses during XMODEM transfers so the protocol has exclusive port access.

For a single text command, prefer serial_execute. It replaces the usual open/command/close sequence with one call and always releases the port, including when command processing fails. It uses 8N1 framing; use an explicit session for multi-step work, other framing, binary data, or triggered responses.

serial_open, serial_status, and serial_list_sessions return explicit lifecycle metadata for every open session:

The deadline moves forward whenever data is read, received, or written. It is the exact point at which the session exceeds its inactivity allowance; the background reaper closes an expired session on its next check, currently within 30 seconds.

Prompts

Four prompts guide common workflows:

Quick example

serial_execute(port="/dev/ttyUSB0", data="uname -a", expect="\\$")
# → runs the command and releases the port

For a shell session requiring multiple commands, use serial_open, serial_command, then serial_close. For unknown devices, run serial_detect_baud() first. Binary protocols use the hex read/write tools, while serial_wait_for(..., respond=" ") can catch time-sensitive boot prompts.

How it works

Each serial_open() creates a SerialSession with a background thread that reads from the port into a timestamped ring buffer (10MB default cap). Data is captured continuously, even between tool calls, so nothing gets lost. serial_read_since() can replay history without advancing the read cursor, and serial_command()/serial_wait_for() scan the buffer for regex matches as data arrives.

Sessions auto-close after a configurable inactivity timeout (default 15 minutes). Lifecycle metadata gives the model the latest activity time and current auto-close deadline rather than only a relative countdown. A background reaper checks every 30 seconds and closes stale sessions. When the AI next tries to use a closed session, it gets a clear error explaining what happened. All tools are async, with blocking serial I/O wrapped in asyncio.to_thread().

Serial output from text tools is normalized (\r\n → \n, trailing whitespace stripped). Binary/hex tools return raw data. Timestamp fields use integer epoch seconds.

When a port is held by another process, serial_open identifies the blocker via lsof and returns the PID and command name so the AI can offer to force-release it.

Testing

No hardware required. Tests use a MockSerial fixture:

uv pip install -e ".[dev]"
pytest -v

Smoke-test the live server with the MCP Inspector:

DANGEROUSLY_OMIT_AUTH=true npx @modelcontextprotocol/inspector -- python3 -m serial_mcp.server

Requirements

• Python >= 3.10
• pyserial >= 3.5
• mcp >= 1.28, < 2
• pydantic >= 2, < 3

License

MIT