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

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:

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

{
  "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

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.