serial-mcp for UART and USB serial access

serial-mcp is an MCP server for direct access to serial ports. It reads, writes, and streams UART or USB-serial data to microcontrollers, Arduino boards, STM32 chips, and other embedded targets. Reads use timeouts and pattern matching instead of blocking on a serial monitor.

The server provides always-on RX capture. It decodes TX and RX frames using line, delimiter, length-prefixed, start/end, SLIP, and COBS formats. It provides AT, JSON, shell, NMEA-0183, and Modbus ASCII parsers.

Protocol presets provide checksum validation. The server also supports auto-reconnect, event logging, DTR/RTS, BREAK, and flow control. MCP clients can use these features with serial bootloaders, resets, and embedded boards.

Quick start

1. Install the server. See Install for Cargo, Nix, and prebuilt binary options.
2. Connect an agent. Follow the agent configuration guide, or use the example below.
3. Discover devices. Call list_ports() and inspect profile_matches. The result shows what a bare open would reuse.
4. Open a port. Call open(port=...) with only the port. Baud defaults to 115200/8-N-1. The server reuses the most recently used high-confidence profile for a known device. It creates a durable generated profile for a new device.
5. Talk to the device. Use transact() for command and response exchanges. Use read() for buffered or unsolicited data. Use write() for send-only operations.

Capabilities

Tool catalog (25 tools)

Resources and prompts

Install

Cargo (all platforms)

cargo install serial-mcp

Nix

nix profile install github:qarnet/serial-mcp

Prebuilt binary

No toolchain is required. Each release publishes one binary per platform. The latest/download URLs resolve to the newest release.

On Linux, add your user to the dialout group for port access:

sudo usermod -aG dialout $USER

Connect an agent

For client-specific setup, see the agent configuration guide. It covers Claude Code CLI, Claude Desktop, Cursor, VS Code, Zed, opencode, Codex, Hermes, and HTTP transport.

{
  "mcpServers": {
    "serial": {
      "type": "stdio",
      "command": "serial-mcp",
      "args": ["--allowlist=/dev/ttyACM*,/dev/ttyUSB*"]
    }
  }
}

Core workflow

Use this sequence for common work: discover, open, talk, verify the learned profile, then use advanced tools when needed.

1. Call list_ports(). Its profile_matches entries correspond to ports.
   • selected means a bare open reuses selected_profile.
   • ambiguous means equal-ranked profiles require open_profile.
   • duplicate, ineligible, and none mean a bare open starts fresh or transient.
2. Call bare open(port=...). The result includes the profile binding. The binding reports its name, source, confidence, persistence, generated flag, revision, and dirty state.
3. Use transact(data=..., match=..., timeout_ms=...) to write and await a response in one call. Use read() for buffered or unsolicited data.
4. After reconfigure, set_flow_control, or connection-mode configure, inspect profile_persistence. It reports persisted, not_needed, transient, or failed. Also inspect the updated profile binding.
5. Call close(). A clean close retries a dirty binding as a safety measure.

For boot and reset capture, call capture_boot. It handles Arduino auto-reset, power-cycle banners, and boot prompts.

The call purges unread OS input. It marks the RX live edge. It can pulse DTR/RTS, with guaranteed release. It captures only post-mark bytes on a private cursor. The result is bounded in memory and does not write a file. See RX and reading for the from cursor model. See Device profiles for profile behavior.

Protocols

The protocol field supplies framing and parser defaults for both directions. NMEA and Modbus ASCII presets validate checksums:

Field precedence is explicit call field, call-time preset, connection default, then connection preset. The Protocol guide documents this order, checksum behavior, and the framing and parser reference.

Key concepts and guides

Transports and options

serial-mcp [OPTIONS]