Serial MCP Server

A stateful serial port Model Context Protocol (MCP) server for developer tooling and AI agents. Works out of the box with Claude Code, VS Code with Copilot, and any MCP-compatible runtime. Communicates over stdio and uses pyserial for cross-platform serial on macOS, Windows, and Linux.

Example: Let Claude Code list available serial ports, connect to your microcontroller, reset it via DTR, and read the boot banner from your hardware.

Demo

Video walkthrough — connecting to a serial device, sending commands, reading responses, and creating plugins.

Why this exists

If you’ve ever copy-pasted commands into screen or minicom, guessed baud rates, toggled DTR to kick a bootloader, and re-run the same test sequence 20 times — this is for you.

You have a serial device. You want an AI agent to talk to it — open a port, send commands, read responses, debug protocols. This server makes that possible.

It gives any MCP-compatible agent a full set of serial tools: listing ports, opening connections, reading, writing, line-oriented I/O, control line manipulation — plus protocol specs and device plugins, so the agent can reason about higher-level device behavior instead of just raw bytes.

The agent calls these tools, gets structured JSON back, and reasons about what to do next — without you manually typing commands into a terminal for every step.

What agents can do with it:

• Develop and debug — connect to your device, send commands, read responses, and diagnose issues conversationally (boot banners, prompts, error codes).
• Iterate on new firmware — attach a protocol spec so the agent understands your command set, boot modes, and output format as they evolve.
• Automate test flows — reset device via DTR, wait for prompt, run a command sequence, validate output.
• Explore unknown devices — probe command sets, discover prompts, infer message formats.
• Build serial automation — long-running test rigs, manufacturing bring-up, CI hardware smoke tests.

Who is this for?

• Embedded engineers — faster iteration on serial protocols, conversational debugging, automated test sequences
• Hobbyists and makers — interact with serial devices without writing boilerplate; let the agent help reverse-engineer simple protocols
• QA and test engineers — build repeatable serial test suites with plugin tools
• Support and field engineers — diagnose serial device issues interactively without specialized tooling
• Researchers — automate data collection from serial devices, explore device capabilities systematically

Quickstart (Claude Code)

pip install serial-mcp-server

# Register the MCP server with Claude Code
claude mcp add serial -- serial_mcp

Then in Claude Code, try:

"List available serial ports and connect to the one on /dev/ttyUSB0 at 115200 baud."

What the agent can do

Once connected, the agent has full serial capabilities:

• List ports to find available serial devices
• Open and close connections with configurable baud rate, parity, stop bits, and encoding
• Read and write data in text, hex, or base64 format
• Line-oriented I/O — readline and read-until-delimiter for text protocols
• Control lines — set or pulse DTR and RTS for hardware reset and boot mode entry
• Flush input and output buffers
• Attach protocol specs to understand device-specific commands and data formats
• Use plugins for high-level device operations instead of raw reads/writes
• Create specs and plugins for new devices so future sessions start "knowing" your protocol
• PTY mirroring — attach screen, minicom, or custom scripts to the same serial session the agent is using

The agent can coordinate multi-step flows automatically — e.g., toggle reset, wait for prompt, send init sequence, stream output.

At a high level:

Raw Serial → Protocol Spec → Plugin

You can start with raw serial tools, then move up the stack as your device protocol becomes understood and repeatable.

Install (development)

# Editable install from repo root
pip install -e .

# Or with uv
uv pip install -e .

MCP is a protocol — this server works with any MCP-compatible client. Below are setup instructions for the most common ones.

Add to Claude Code

# Standard setup
claude mcp add serial -- serial_mcp

# Or run as a module
claude mcp add serial -- python -m serial_mcp_server

# Enable all plugins
claude mcp add serial -e SERIAL_MCP_PLUGINS=all -- serial_mcp

# Enable specific plugins only
claude mcp add serial -e SERIAL_MCP_PLUGINS=mydevice,ota -- serial_mcp

# Debug logging
claude mcp add serial -e SERIAL_MCP_LOG_LEVEL=DEBUG -- serial_mcp

Add to VS Code / Copilot

Add to your project's .vscode/mcp.json (or create it):

{
  "servers": {
    "serial": {
      "type": "stdio",
      "command": "serial_mcp",
      "args": [],
      "env": {
        "SERIAL_MCP_PLUGINS": "all"
      }
    }
  }
}

Adjust env to match your needs — set SERIAL_MCP_PLUGINS to specific plugin names, or add SERIAL_MCP_MIRROR for PTY mirroring.

Add to Cursor

Add to your project's .cursor/mcp.json (or create it). Cursor does not support dots in tool names, so SERIAL_MCP_TOOL_SEPARATOR must be set to _:

{
  "mcpServers": {
    "serial": {
      "command": "serial_mcp",
      "args": [],
      "env": {
        "SERIAL_MCP_PLUGINS": "all",
        "SERIAL_MCP_TOOL_SEPARATOR": "_"
      }
    }
  }
}

Environment variables

Tools

Protocol Specs

Specs are markdown files that describe a serial device's protocol — connection settings, message format, commands, and multi-step flows. They live in .serial_mcp/specs/ and teach the agent what the byte stream means.

Without a spec, the agent can still open a port and exchange data. With a spec, it knows what commands to send, what responses to expect, and what the data means.

You can create specs by telling the agent about your device — paste a datasheet, describe the protocol, or just let it explore and document what it finds. The agent generates the spec file, registers it, and references it in future sessions. You can also write specs by hand.

Plugins

Plugins add device-specific shortcut tools to the server. Instead of the agent composing raw read/write sequences, a plugin provides high-level operations like mydevice.read_temp or ota.upload_firmware.

The agent can also generate Python plugins (with your approval). It explores a device, writes a plugin based on what it learns, and future sessions get shortcut tools — no manual coding required.

To enable plugins:

# Enable all plugins
claude mcp add serial -e SERIAL_MCP_PLUGINS=all -- serial_mcp

# Enable specific plugins only
claude mcp add serial -e SERIAL_MCP_PLUGINS=mydevice,ota -- serial_mcp

Editing an already-loaded plugin only requires serial.plugin.reload — no restart needed.

Tracing

Every tool call is traced to .serial_mcp/traces/trace.jsonl and an in-memory ring buffer (last 2000 events). Tracing is on by default — set SERIAL_MCP_TRACE=0 to disable.

Event format

Two events per tool call:

{"ts":"2025-01-01T00:00:00.000Z","event":"tool_call_start","tool":"serial.read","args":{"connection_id":"s1"},"connection_id":"s1"}
{"ts":"2025-01-01T00:00:00.050Z","event":"tool_call_end","tool":"serial.read","ok":true,"error_code":null,"duration_ms":50,"connection_id":"s1"}