MCP Serial Server

FastMCP server for serial port access via Model Context Protocol.

Documentation | PyPI | Source

Features

• RS-232 Mode: Full modem control (RTS, DTR, CTS, DSR, RI, CD, break condition)
• RS-422 Mode: Full-duplex differential point-to-point (or 1-to-10 receivers) over long distances
• RS-485 Mode: Half-duplex bus communication with auto direction control
• File Transfer: X/Y/ZMODEM protocols for reliable file transfers
• Auto-baud Detection: Smart detection using 0x55 sync pattern analysis
• URL Handlers: Open remote/virtual ports (socket://, rfc2217://, loop://, spy://, cp2110://)
• Dynamic Resources: Read data via serial://{port}/data
• Full pyserial support (baudrate, parity, stop bits, flow control)

Installation

# With uvx (recommended)
uvx mcserial

# Or install directly
uv pip install mcserial

# With CP2110 HID-to-UART support
uv pip install mcserial[cp2110]

Usage with Claude Code

# Add to Claude Code
claude mcp add mcserial "uvx mcserial"

Modes

Ports open in RS-232 mode by default. Switch with set_port_mode() or pass mode= to open_serial_port():

Tools

Common (all modes)

RS-232 Mode

RS-422 Mode

RS-485 Mode

File Transfer

Protocols:

• xmodem - 128-byte blocks, simple (1977)
• xmodem1k - 1024-byte blocks
• ymodem - Batch mode with filename/size
• zmodem - Streaming, auto-resume (recommended)

URL Handlers

The open_serial_port tool accepts URL schemes in addition to local device paths:

URL-opened ports skip auto-baud detection and exclusive access (not applicable to virtual/network ports).

Resources

Environment Variables

Example Workflows

Basic RS-232

1. list_serial_ports() → find /dev/ttyUSB0
2. open_serial_port(port="/dev/ttyUSB0")  # auto-detects baud
3. configure_serial(port="/dev/ttyUSB0", line_ending="crlf")  # auto-append \r\n
4. transact(port="/dev/ttyUSB0", data="AT")  # send + read in one call
5. close_serial_port(port="/dev/ttyUSB0")

Filter Ports by Hardware

1. list_serial_ports(grep="FTDI")       # find all FTDI devices
2. list_serial_ports(grep="CP210")      # find Silicon Labs adapters
3. list_serial_ports(grep="VID:PID=0403:6001")  # exact USB ID match

RS-422 Differential Link

1. open_serial_port(port="/dev/ttyUSB0", baudrate=9600, mode="rs422")
2. configure_serial(port="/dev/ttyUSB0", line_ending="crlf")
3. transact(port="/dev/ttyUSB0", data="READ TEMP")  # full-duplex, no direction control
4. check_rs422_support(port="/dev/ttyUSB0")

RS-485 Modbus

1. open_serial_port(port="/dev/ttyUSB0", baudrate=9600, mode="rs485")
2. rs485_scan_addresses(port="/dev/ttyUSB0")  # discover devices
3. rs485_transact(port="/dev/ttyUSB0", data="\x01\x03...")

Network Serial (serial-to-ethernet bridge)

1. open_serial_port(port="socket://192.168.1.100:4001", baudrate=115200)
2. write_serial(port="socket://192.168.1.100:4001", data="AT\r\n")
3. read_serial(port="socket://192.168.1.100:4001")

Loopback Testing (no hardware needed)

1. open_serial_port(port="loop://", baudrate=9600)
2. write_serial(port="loop://", data="hello")
3. read_serial(port="loop://")  # → "hello"
4. close_serial_port(port="loop://")

File Transfer

1. open_serial_port(port="/dev/ttyUSB0", baudrate=115200)
2. file_transfer_send(port="/dev/ttyUSB0", file_path="firmware.bin")

License

MIT