Ryan Malloy
b5bd2bb470
Reorganized tool tables by mode (RS-232, RS-485, file transfer) and added usage examples for Modbus bus scanning and ZMODEM transfers.
141 lines
4.1 KiB
Markdown
141 lines
4.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# With uvx (recommended)
|
|
uvx mcserial
|
|
|
|
# Or install directly
|
|
uv pip install mcserial
|
|
```
|
|
|
|
## Usage with Claude Code
|
|
|
|
```bash
|
|
# 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
|