# serial-mcp

An MCP server that lets Claude (or any MCP client) read the serial output of a device.

## Why this exists

Reading serial logs is a blocking, long-running operation that streams output indefinitely. An AI agent cannot simply open a serial port and wait for it to close, because it never closes. The agent would hang, unable to do anything else while the port is open.

This MCP server solves the problem by opening the serial port in the background via `pyserial-asyncio`, buffering output line-by-line, and letting the agent poll for new lines on demand. The agent can start monitoring, go do other work, and come back to read the logs whenever it needs to — checking for crash backtraces, boot messages, sensor readings, or any other serial output.

## Installation

```bash
pip install -e ".[dev]"
```

Requires Python 3.10+.

## Configuration

| Environment variable | Default | Description |
|---|---|---|
| `SERIAL_MCP_MAX_BUFFER` | unlimited | Maximum number of lines kept in the buffer. When exceeded, the oldest lines are discarded first. |

## MCP Tools

The server exposes three tools over stdio transport:

### `start_buffering(device, baudrate=115200)`

Opens the serial port at the given path (e.g. `/dev/ttyUSB0`) and baud rate. If a monitor is already running, it is stopped first and replaced. Output begins accumulating in memory immediately.

### `next_chunk(nlines=50, pattern=None)`

Returns the next batch of buffered lines the agent hasn't seen yet. Each response includes a status header:

```
[lines=12 remaining=0 running=true]
I (324) cpu_start: Starting scheduler on PRO CPU.
I (330) main_task: Started on CPU0
...
```

- `lines` — number of lines in this response (when filtered, shows `matched/total`)
- `remaining` — unread lines still in the buffer after this batch
- `running` — whether the serial reader is still alive

The optional `pattern` parameter filters output using a regular expression. Only lines matching the pattern are returned. This is useful for reducing token consumption when dealing with verbose output:

```python
# Only show ERROR lines
next_chunk(100, pattern="ERROR")

# Show temperature readings
next_chunk(50, pattern=r"Temperature: \d+\.\d+")
```

Call this repeatedly to drain all output. When there is nothing new, it returns `(no new output)`.

### `stop_buffering()`

Closes the serial port. The buffer is preserved, so `next_chunk` can still be called to read any remaining output.

## Usage with Claude Code

Add the server to your MCP configuration (e.g. `.mcp.json` in your project):

```json
{
  "mcpServers": {
    "serial-mcp": {
      "command": "serial-mcp"
    }
  }
}
```

Then Claude can use it as part of a natural workflow:

1. **Start the monitor** via `start_buffering("/dev/ttyUSB0")`
2. **Do other work** — edit source files, review code, build, flash, etc.
3. **Poll for logs** via `next_chunk()` to check what the device printed
4. **Stop the monitor** via `stop_buffering()` when done

## Running tests

```bash
pytest tests/ -v
```

All tests use mocked serial connections — no hardware required.

## How it works

- The serial port is opened via `pyserial-asyncio` using `open_serial_connection(url=device, baudrate=baudrate)`.
- A background `asyncio.Task` reads the port line-by-line and appends to an in-memory list.
- `next_chunk()` is a simple cursor-based read — it slices the list from where the agent last left off and advances the cursor. No locking is needed because everything runs in a single-threaded asyncio event loop.
- UTF-8 decoding uses `errors="replace"` to handle garbled serial data gracefully.