MCP Serial Server

FastMCP server for serial port access via Model Context Protocol.

Features

• RS-232 Mode: Full modem control (RTS, DTR, CTS, DSR, RI, CD)
• 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
• 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

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():

Mode	Use Case	Tools
RS-232	Point-to-point serial	get_modem_lines, set_modem_lines, pulse_line, send_break
RS-485	Multi-drop bus (Modbus)	set_rs485_mode, rs485_transact, rs485_scan_addresses

Tools

Common (both modes)

Tool	Description
list_serial_ports	Discover available serial ports
open_serial_port	Open connection (auto-detects baud if not specified)
close_serial_port	Close a connection
set_port_mode	Switch between RS-232 and RS-485 modes
write_serial	Send text data
write_serial_bytes	Send raw bytes
read_serial	Read available data
read_serial_line	Read until newline
read_until	Read until custom terminator
configure_serial	Change port settings
flush_serial	Clear buffers
get_connection_status	List open connections with mode
detect_baud_rate	Auto-detect baud rate

RS-232 Mode

Tool	Description
get_modem_lines	Read CTS, DSR, RI, CD, RTS, DTR states
set_modem_lines	Control RTS and DTR outputs
pulse_line	Pulse RTS/DTR for reset sequences
send_break	Send timed break signal
set_break_condition	Hold/release break state

RS-485 Mode

Tool	Description
set_rs485_mode	Configure hardware RS-485 (DE/RE control)
check_rs485_support	Detect hardware RS-485 capability
rs485_transact	Send/receive with automatic turnaround
rs485_scan_addresses	Scan bus for responding devices

File Transfer

Tool	Description
file_transfer_send	Send file via XMODEM/YMODEM/ZMODEM
file_transfer_receive	Receive file via XMODEM/YMODEM/ZMODEM
file_transfer_send_batch	Send multiple files (YMODEM/ZMODEM)

Protocols:

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

Resources

URI	Description
serial://ports	List available ports
serial://{port}/data	Read data from open port
serial://{port}/status	Port config and mode
serial://{port}/raw	Read as hex dump

Environment Variables

Variable	Default	Description
MCSERIAL_DEFAULT_BAUDRATE	9600	Default baud rate
MCSERIAL_DEFAULT_TIMEOUT	1.0	Read timeout (seconds)
MCSERIAL_MAX_CONNECTIONS	10	Max concurrent ports

Example Workflows

Basic RS-232

1. list_serial_ports() → find /dev/ttyUSB0
2. open_serial_port(port="/dev/ttyUSB0")  # auto-detects baud
3. write_serial(port="/dev/ttyUSB0", data="AT\r\n")
4. Read resource: serial:///dev/ttyUSB0/data
5. close_serial_port(port="/dev/ttyUSB0")

RS-485 Modbus

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

File Transfer

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

License

MIT