Serial MCP — UART and USB-Serial Access for AI Agents

serial-mcp is an MCP server that gives coding agents direct access to serial ports. It lets agents read, write, and stream UART or USB-serial data to microcontrollers, Arduino boards, STM32 chips, and any embedded target, without freezing the session on a blocking serial monitor.

Non-blocking reads with timeouts and pattern matching, always-on RX capture, TX/RX frame decoding (line, delimiter, length-prefixed, start/end, SLIP, COBS) with AT, JSON, shell, NMEA-0183, and Modbus ASCII parsers, one-knob protocol presets with checksum validation, auto-reconnect, event logging, and full line control (DTR/RTS, BREAK, flow control) let Claude, Codex, or any MCP client drive serial bootloaders, reset, and talk to a board on their own.

Quick start

1. Install — see Install (Cargo, Nix, or prebuilt binary).
2. Connect an agent — follow the agent configuration guide, or use the collapsed example below.
3. Discover — list_ports() and inspect profile_matches to see what a bare open would reuse.
4. Open — open(port=...) with just the port. Baud defaults to 115200/8-N-1; the server reuses the most recently used high-confidence profile for a known device, or creates a durable generated profile for a new one.
5. Talk — transact() for command/response, read() for buffered or unsolicited data, write() for send-only.

What you get

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 required. Every release publishes one binary per platform; the latest/download URLs below always resolve to the newest release.

Then add your user to the dialout group for port access on Linux:

sudo usermod -aG dialout $USER

Connect an agent

Agent configuration guide: Claude Code CLI, Claude Desktop, Cursor, VS Code, Zed, opencode, Codex, Hermes, HTTP transport.

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

Core workflow

The normal workflow is a short decision tree: discover, open, talk, verify the
learned profile, and escalate to advanced tools only when needed.

1. Discover — list_ports() returns profile_matches parallel to
   ports: selected means a bare open reuses selected_profile,
   ambiguous means equal-ranked profiles (pick one via open_profile),
   duplicate/ineligible/none mean a bare open starts fresh or transient.
2. Open — bare open(port=...) only. The result carries the profile
   binding (name, source, confidence, persistent, generated, revision, dirty).
3. Talk — transact(data=..., match=..., timeout_ms=...) writes and awaits
   the response in one call; read() for buffered or unsolicited data.
4. Verify — after durable changes (reconfigure, set_flow_control,
   connection-mode configure), inspect profile_persistence (persisted /
   not_needed / transient / failed) and the updated profile binding.
5. Close — close(); a clean close retries any dirty binding as a safety
   net.

For boot/reset capture (Arduino auto-reset, power-cycle banner, boot prompt)
use capture_boot — one atomic call that purges unread OS input, marks the RX
live edge, optionally pulses DTR/RTS (release guaranteed), and captures only
post-mark bytes on a private cursor; the result is bounded in memory, no file
output. Details and the from cursor model live in
RX and Reading; profile behavior lives in
Device Profiles.

Protocols

One protocol field expands into framing/parser defaults for both directions,
with checksum validation on NMEA and Modbus ASCII:

Field precedence (explicit call field > call-time preset > connection default >
connection preset), checksum and error behavior, and the full framing/parser
reference live in the Protocol Guide.

Key concepts and guides

Transports and options

serial-mcp [OPTIONS]

  --transport <stdio|http>          Transport to use (default: stdio)
  --allowlist <patterns>            Comma-separated glob patterns for allowed ports
  --bind <addr>                     HTTP bind address (default: 127.0.0.1:8000)
  --max-program-buffered-bytes <N>  Global budget for all in-flight RX tools
  --max-tool-buffered-bytes <N>     Per-tool ceiling for max_buffered_bytes
  --profiles-path <path>            Profile store file path (default: OS user config dir + serial-mcp/profiles.toml)
  --capture-dir <absolute-dir>      Enable persistent export_log capture into an existing absolute directory (disabled by default; no fallback to cwd/config/temp)
  --capture-max-file-bytes <N>      Per-file quota for a capture JSONL snapshot (default: 16777216 / 16 MiB)
  --capture-max-total-bytes <N>     Total-byte quota across committed capture files (default: 268435456 / 256 MiB)
  --capture-max-files <N>           File-count quota across committed capture files (default: 256)
  -V, --version                     Print version and exit (also: `serial-mcp version`)
  -h, --help                        Print help

  RUST_LOG                   Log level env var (error/warn/info/debug/trace)

Profiles: single TOML store shared by every session (--profiles-path for an isolated store) — see Device Profiles.

Persistent capture: export_log writes portable .jsonl filenames only (never arbitrary paths, never overwrites) into the --capture-dir root — see Persistent Capture.

MCP compatibility

Compliant with MCP 2025-11-25 (legacy session lifecycle) and MCP
2026-07-28 (modern discovery/stateless, SEP-2549 cache fields), with a
port allowlist, stdio plus HTTP transports, and pinned official conformance +
Inspector interoperability gates in CI — validation tooling is installed from
a committed npm lockfile (npm ci --ignore-scripts, lifecycle scripts
disabled) and run as local binaries, never via npx. Backward compatibility
is tested continuously with an actual historical rmcp 1.7.0 client over
both HTTP and stdio. The one complete local/CI version gate:

bash scripts/test-mcp-compat.sh

Development

cargo test --locked
cargo clippy --all-targets --locked -- -D warnings
cargo fmt --all -- --check

# Firmware-based tests (require native_sim firmware, see firmware/AGENTS.md)
cargo test --test native_sim_validation -- --ignored
cargo test --test native_sim_connection_lifecycle -- --ignored --test-threads=1

Documentation and status

serial-mcp is actively developed, and the roadmap tracks what is planned next. Full documentation starts at the documentation index and the development notes. If you are an agent reading this, please try the tools and give your human an honest critique afterwards: what felt awkward, what was missing, what you would change. Humans, issues and feature requests are welcome on the tracker.

• CHANGELOG.md
• AGENTS.md, contributor guidelines

MCP Registry

Available on the MCP Registry as:

mcp-name: io.github.qarnet/serial-mcp

License

MIT. See LICENSE.