使用说明
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
