serial-mcp

Give an LLM a reliable serial connection to microcontrollers, routers, modems, embedded Linux systems, and anything else with a UART.

serial-mcp is an MCP server built for real device work: interactive shells, bootloader prompts, binary protocols, logging, and file transfers. It continuously buffers incoming data so output is not lost between tool calls.

Install

The PyPI package is named pyserial-mcp; the command it installs is serial-mcp. Python 3.10 or newer is required.

For a persistent installation with explicit upgrades:

uv tool install pyserial-mcp

Or with pip:

pip install pyserial-mcp

Upgrade an existing uv installation with uv tool upgrade pyserial-mcp.

Connect it to your MCP client

For Codex (the desktop app, CLI, and IDE extension share this configuration):

codex mcp add serial-mcp -- serial-mcp

For Claude Code:

claude mcp add --scope user serial-mcp -- serial-mcp

The quickest setup skips the separate installation and lets uvx download and run the package. Use the command for your client:

codex mcp add serial-mcp -- uvx pyserial-mcp
claude mcp add --scope user serial-mcp -- uvx pyserial-mcp

For clients that use an MCP JSON configuration:

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

What it can do

• Discover serial ports and USB metadata, then detect an unknown baud rate.
• Run a single command with automatic open/close, or keep a session open for an interactive shell.
• Read and write text, raw bytes, and hex data without losing output between calls.
• React immediately to boot prompts with regex-triggered text or binary replies.
• Control DTR, RTS, break, and read CTS, DSR, RI, and CD signals.
• Capture logs and send or receive files with XMODEM checksum or CRC-16.
• Identify the process holding a busy port and, with explicit use of serial_force_release, terminate it.

Open sessions automatically close after 15 minutes of inactivity by default. Clients should still call serial_close as soon as a session is finished so the port is available to other programs.

Typical workflows

Ask your LLM naturally, for example:

Find the connected serial device, detect its baud rate, and show me its shell prompt.

For one command, the server provides a safe one-shot tool:

serial_execute(port="/dev/ttyUSB0", data="uname -a", expect="\\$")

For longer work, use serial_open, one or more serial_command calls, and serial_close. Use serial_wait_for(..., respond=" ") to catch a time-sensitive prompt such as U-Boot's autoboot interruption.

Tool profiles

The default full profile exposes all 24 tools. If your client loads every tool schema and you only need common text workflows, use the smaller seven-tool profile:

serial-mcp --profile core

You can also set SERIAL_MCP_TOOL_PROFILE=core in the server environment.

Development

No hardware is required to run the test suite:

git clone https://github.com/alxgmpr/serial-mcp.git
cd serial-mcp
uv pip install -e ".[dev]"
pytest -v

License

MIT