Skip to main content
Glama
serial-mcp

serial-mcp

by alxgmpr
README.md
# 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.

![Claude using serial-mcp to inspect a connected device](https://github.com/user-attachments/assets/17e948ae-4888-4748-8694-77c1e257e329)

## 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

B3.1/5.0

Scored across 24 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count3/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessOutdated data