serial-mcp
# 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](https://modelcontextprotocol.io/) 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. Serial I/O is handled by
[serialx](https://github.com/puddly/serialx), and the server is built on the
[MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) 2.x.
Clients that support elicitation are prompted to pick a port (when several are
connected) and to confirm a detected baud rate, on both the 2025-11-25 and
2026-07-28 protocols. Other clients get the same information back as tool output.

## 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:
```sh
uv tool install pyserial-mcp
```
Or with pip:
```sh
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):
```sh
codex mcp add serial-mcp -- serial-mcp
```
For Claude Code:
```sh
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:
```sh
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:
```json
{
"mcpServers": {
"serial": {
"command": "uvx",
"args": ["pyserial-mcp"]
}
}
}
```
## What it can do
- Discover serial ports and USB metadata, then detect an unknown baud rate.
- Open local devices or ports exposed over the network: `socket://host:port`
(ser2net, socat) and `rfc2217://host:port`.
- 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:
```text
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:
```sh
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:
```sh
git clone https://github.com/alxgmpr/serial-mcp.git
cd serial-mcp
uv pip install -e ".[dev]"
pytest -v
```
## License
[MIT](LICENSE)
TDQS
Scored across 24 tools
Most tools target clearly distinct operations (read vs read_since vs read_hex are well differentiated by consuming vs non-consuming and text vs binary semantics; write vs write_hex likewise). The boundaries between serial_execute, serial_command, and serial_wait_for are subtler since all send/wait for output, but the descriptions spell out the differences (one-shot close, regex/timeout collection, passive wait-and-respond). Only minor potential confusion remains.
Nearly all tools follow a predictable serial_verb_noun pattern (serial_open, serial_read, serial_write_hex). The one outlier is list_serial_ports, which puts the noun before receiving a serial_ prefix, a small inconsistency. Otherwise the convention is stable and readable.
24 tools is on the heavy side for a serial-port server and pushes into the borderline range. While each tool covers a genuinely different capability (signals, hex I/O, XMODEM, logging, baud detection), the surface feels large enough that some consolidation (e.g. read variants) could have trimmed it.
The surface covers a full lifecycle: open/close/force-release, settings changes, text and hex read/write, signal control, break, baud detection, history, logging, and XMODEM transfer. A minor gap is the absence of a get-settings/read-back tool to complement serial_change_settings, but overall coverage is strong.