---
title: mcserial
description: MCP server for serial port communication -- RS-232, RS-485, and file transfers via Model Context Protocol.
template: splash
hero:
  tagline: Serial ports meet the Model Context Protocol. Discover, configure, read, write, and transfer files -- RS-232, RS-485, and 7 URL schemes, all callable as MCP tools.
  image:
    file: ../../assets/logo.svg
  actions:
    - text: Get Started
      link: /tutorials/getting-started/
      icon: right-arrow
      variant: primary
    - text: Tool Reference
      link: /reference/tools-common/
      variant: minimal
---

import { Card, CardGrid, Aside } from '@astrojs/starlight/components';

## What mcserial does

<CardGrid stagger>
  <Card title="RS-232 and RS-485" icon="setting">
    Full RS-232 modem line control -- RTS, DTR, CTS, DSR, break signals, device reset pulses. Switch to RS-485 mode for half-duplex bus communication with automatic TX/RX direction, device scanning, and Modbus transactions.
  </Card>
  <Card title="File Transfers" icon="document">
    Send and receive files over serial using XMODEM (128B blocks), XMODEM-1K, YMODEM (batch mode), or ZMODEM (streaming with auto-resume). Batch transfers supported for YMODEM and ZMODEM.
  </Card>
  <Card title="Network and Virtual Ports" icon="external">
    Connect to serial-over-ethernet bridges via `socket://`, configure remote ports with `rfc2217://`, test without hardware on `loop://`, or debug traffic with `spy://`. Seven URL schemes total.
  </Card>
  <Card title="Baud Rate Detection" icon="random">
    Omit the baud rate when opening a port and mcserial will detect it automatically by analyzing data patterns, sync bytes, and byte distributions. Returns a confidence score and ranked candidates.
  </Card>
</CardGrid>

## Quick start

Install mcserial and register it with your MCP client:

```bash
# Add to Claude Code (one-time setup)
claude mcp add mcserial -- uvx mcserial
```

Then ask your assistant to work with serial ports. It calls the tools behind the scenes:

```
list_serial_ports()                          # find available ports
open_serial_port(port="loop://", baudrate=9600)   # open (loop:// = no hardware needed)
write_serial(port="loop://", data="hello\n")      # send data
read_serial(port="loop://")                       # read response
close_serial_port(port="loop://")                  # release the port
```

You interact in natural language -- "list my serial ports," "open the loopback port at 9600 baud," "send hello." See the [Getting Started tutorial](/tutorials/getting-started/) for the full walkthrough with example responses.

## Supported URL schemes

In addition to local device paths (`/dev/ttyUSB0`, `COM3`), `open_serial_port` accepts these URL schemes:

| Scheme | Description | Example |
|--------|-------------|---------|
| `loop://` | In-memory loopback -- writes echo back as reads | `loop://` |
| `socket://` | Raw TCP socket for serial-to-ethernet bridges | `socket://192.168.1.100:4001` |
| `rfc2217://` | Telnet COM Port Control with remote baud/flow config | `rfc2217://192.168.1.100:2217` |
| `spy://` | Debug wrapper that logs all traffic to stderr | `spy:///dev/ttyUSB0` |
| `hwgrep://` | Open first port matching a hardware pattern | `hwgrep://FTDI` |
| `cp2110://` | Silicon Labs HID-to-UART (requires `[cp2110]` extra) | `cp2110://` |
| `alt://` | Alternate port backend | `alt:///dev/ttyUSB0` |

## 30 tools across 4 categories

mcserial is a [FastMCP](https://gofastmcp.com) server wrapping [pyserial](https://pyserial.readthedocs.io/) into organized tool groups:

- **[Common tools](/reference/tools-common/)** (18) -- port discovery, open/close, read/write, configuration, baud detection
- **[RS-232 tools](/reference/tools-rs232/)** (5) -- modem line control, break signals, reset pulses
- **[RS-485 tools](/reference/tools-rs485/)** (4) -- bus configuration, transactions, address scanning
- **[File transfer tools](/reference/tools-file-transfer/)** (3) -- X/Y/ZMODEM send, receive, batch send

Ports open in RS-232 mode by default. Use `set_port_mode()` to switch to RS-485 when working with multi-drop buses. Common tools work in both modes.
