# 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