{
  "markdown": "# serial-mcp for UART and USB serial access\n\n[![GitHub Release](https://img.shields.io/github/v/release/qarnet/serial-mcp)](https://github.com/qarnet/serial-mcp/releases)\n[![crates.io](https://img.shields.io/crates/v/serial-mcp)](https://crates.io/crates/serial-mcp)\n[![Rust](https://img.shields.io/badge/rust-1.97.1-orange.svg)](https://rust-lang.org)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\n`serial-mcp` is an MCP server for direct access to serial ports. It reads,\nwrites, and streams UART or USB-serial data to microcontrollers, Arduino boards,\nSTM32 chips, and other embedded targets. Reads use timeouts and pattern matching\ninstead of blocking on a serial monitor.\n\nThe server provides always-on RX capture. It decodes TX and RX frames using\nline, delimiter, length-prefixed, start/end, SLIP, and COBS formats. It provides\nAT, JSON, shell, NMEA-0183, and Modbus ASCII parsers.\n\nProtocol presets provide checksum validation. The server also supports\nauto-reconnect, event logging, DTR/RTS, BREAK, and flow control. MCP clients can\nuse these features with serial bootloaders, resets, and embedded boards.\n\n## Quick start\n\n1. Install the server. See [Install](#install) for Cargo, Nix, and prebuilt binary options.\n2. Connect an agent. Follow the [agent configuration guide](docs/guides/agent-configuration.md), or use the example below.\n3. Discover devices. Call `list_ports()` and inspect `profile_matches`. The result shows what a bare `open` would reuse.\n4. Open a port. Call `open(port=...)` with only the port.\n   Baud defaults to 115200/8-N-1. The server reuses the most recently used\n   high-confidence profile for a known device. It creates a durable generated\n   profile for a new device.\n5. Talk to the device. Use `transact()` for command and response exchanges. Use `read()` for buffered or unsolicited data. Use `write()` for send-only operations.\n\n## Capabilities\n\n| Area | What it provides |\n|---|---|\n| RX model | An always-on ring buffer captures bytes from open to close. `read` returns buffered bytes immediately. It can also wait, match, and replay history. |\n| Framing and parsing | Both directions support line, delimiter, length-prefixed, start/end, SLIP, and COBS framing. Parsers include AT, JSON, shell, NMEA-0183, and Modbus ASCII. |\n| Protocol presets | Seven presets are available. They are `at_command`, `slip`, `json_lines`, `cobs`, `ndjson`, `nmea0183`, and `modbus_ascii`. Checksum validation is included. |\n| Device profiles | The server creates automatic profile sessions. High-confidence devices get durable generated profiles. Learned settings persist across sessions. |\n| Boot capture | `capture_boot` handles Arduino auto-reset, power-cycle banners, and boot prompts in one atomic call. |\n| Reliability | Ring wrap is reported through `bytes_lost`. Encoding fallback is lossless. The server also supports auto-reconnect and reports partial failures. |\n| Operations | Event logging supports persistent JSONL capture through `export_log`. The server also provides port allowlisting and stdio and HTTP transports. |\n\n## Tool catalog (25 tools)\n\n| Group | Tools |\n|---|---|\n| Discovery | `list_ports`, `list_connections` |\n| Connection lifecycle | `open`, `close`, `reconnect`, `get_status`, `reconfigure` |\n| I/O | `read`, `write`, `transact`, `capture_boot`, `flush` |\n| Line control | `set_dtr_rts`, `set_flow_control`, `send_break` |\n| Profiles & config | `list_profiles`, `open_profile`, `save_profile`, `delete_profile`, `configure`, `rollback_profile` |\n| Logs & capture | `get_log`, `clear_log`, `export_log` |\n| Utility | `compute_checksum` |\n\n## Resources and prompts\n\n| Kind | Items |\n|---|---|\n| Resources (5) | `serial://ports`, `serial://connections` (static); `serial://connections/{id}`, `serial://connections/{id}/raw`, `serial://connections/{id}/log` (templates) |\n| Prompts (2) | `diagnose_port`, `interactive_terminal` |\n\n## Install\n\n### Cargo (all platforms)\n\n```bash\ncargo install serial-mcp\n```\n\n### Nix\n\n```bash\nnix profile install github:qarnet/serial-mcp\n```\n\n### Prebuilt binary\n\nNo toolchain is required. Each release publishes one binary per platform. The\n`latest/download` URLs resolve to the newest release.\n\n| Platform | Command |\n|---|---|\n| Linux x86_64 | `curl -L https://github.com/qarnet/serial-mcp/releases/latest/download/serial-mcp-x86_64-linux -o serial-mcp && sudo install -m 755 serial-mcp /usr/local/bin/` |\n| Linux ARM64 | Same command with the `serial-mcp-aarch64-linux` asset |\n| macOS (Apple Silicon) | Same command with the `serial-mcp-aarch64-macos` asset |\n| Windows (x86_64) | Download [`serial-mcp-x86_64-windows.exe`](https://github.com/qarnet/serial-mcp/releases/latest/download/serial-mcp-x86_64-windows.exe) and place it on your `PATH` |\n\nOn Linux, add your user to the `dialout` group for port access:\n\n```bash\nsudo usermod -aG dialout $USER\n```\n\n## Connect an agent\n\nFor client-specific setup, see the [agent configuration guide](docs/guides/agent-configuration.md).\nIt covers Claude Code CLI, Claude Desktop, Cursor, VS Code, Zed, opencode,\nCodex, Hermes, and HTTP transport.\n\n<details>\n<summary>Quick example (Claude Code, Linux/macOS)</summary>\n\n```json\n{\n  \"mcpServers\": {\n    \"serial\": {\n      \"type\": \"stdio\",\n      \"command\": \"serial-mcp\",\n      \"args\": [\"--allowlist=/dev/ttyACM*,/dev/ttyUSB*\"]\n    }\n  }\n}\n```\n\n</details>\n\n## Core workflow\n\nUse this sequence for common work: discover, open, talk, verify the learned\nprofile, then use advanced tools when needed.\n\n1. Call `list_ports()`. Its `profile_matches` entries correspond to `ports`.\n   - `selected` means a bare `open` reuses `selected_profile`.\n   - `ambiguous` means equal-ranked profiles require `open_profile`.\n   - `duplicate`, `ineligible`, and `none` mean a bare open starts fresh or transient.\n2. Call bare `open(port=...)`. The result includes the `profile` binding. The binding reports its name, source, confidence, persistence, generated flag, revision, and dirty state.\n3. Use `transact(data=..., match=..., timeout_ms=...)` to write and await a response in one call. Use `read()` for buffered or unsolicited data.\n4. After `reconfigure`, `set_flow_control`, or connection-mode `configure`,\n   inspect `profile_persistence`. It reports `persisted`, `not_needed`,\n   `transient`, or `failed`. Also inspect the updated `profile` binding.\n5. Call `close()`. A clean close retries a dirty binding as a safety measure.\n\nFor boot and reset capture, call `capture_boot`. It handles Arduino auto-reset,\npower-cycle banners, and boot prompts.\n\nThe call purges unread OS input. It marks the RX live edge. It can pulse DTR/RTS,\nwith guaranteed release. It captures only post-mark bytes on a private cursor.\nThe result is bounded in memory and does not write a file. See [RX and\nreading](docs/guides/rx-and-reading.md) for the `from` cursor model. See [Device\nprofiles](docs/guides/device-profiles.md) for profile behavior.\n\n## Protocols\n\nThe `protocol` field supplies framing and parser defaults for both directions.\nNMEA and Modbus ASCII presets validate checksums:\n\n| Preset | Wire name | Framing / parser |\n|---|---|---|\n| AT commands | `at_command` | Line (CR) + AT parser |\n| SLIP | `slip` | RFC 1055 byte stuffing |\n| JSON lines | `json_lines` | Line + JSON-lines parser |\n| COBS | `cobs` | Consistent Overhead Byte Stuffing |\n| NDJSON | `ndjson` | Line + JSON-lines parser, skips blank lines |\n| NMEA-0183 | `nmea0183` | Start/end `$`/`!` + NMEA parser, `*XX` checksum |\n| Modbus ASCII | `modbus_ascii` | Start/end `:` + Modbus ASCII parser, LRC |\n\nField precedence is explicit call field, call-time preset, connection default,\nthen connection preset. The [Protocol guide](docs/guides/protocols.md) documents this\norder, checksum behavior, and the framing and parser reference.\n\n## Key concepts and guides\n\n| Guide | What it covers |\n|---|---|\n| [RX and reading](docs/guides/rx-and-reading.md) | Ring buffer and shared cursor. Tagged `from` forms. Timeouts, silence, and matching. Ring wrap and `bytes_lost`. Encoding fallback, flow control, `capture_boot`, and subscriptions. |\n| [Device profiles](docs/guides/device-profiles.md) | `profile_matches` outcomes and identity rules. Generated and reused selection. Learning, revision CAS, rollback, and deletion guards. |\n| [Persistent capture](docs/guides/persistent-capture.md) | The `export_log` contract. Quotas, portable filenames, atomicity, and failure semantics. |\n| [Agent configuration](docs/guides/agent-configuration.md) | Client setup. HTTP transport. Troubleshooting. |\n| [Protocol guide](docs/guides/protocols.md) | Framing and parsers. Presets and precedence. Checksum behavior. |\n| [Documentation index](docs/README.md) | User and development guides |\n\n## Transports and options\n\n| Mode | How to activate | Use case |\n|---|---|---|\n| stdio | default | Desktop agents |\n| HTTP | `--transport=http` | Remote and headless use |\n\n<details>\n<summary>CLI options</summary>\n\n```\nserial-mcp [OPTIONS]\n\n  --transport <stdio|http>          Transport to use (default: stdio)\n  --allowlist <patterns>            Comma-separated glob patterns for allowed ports\n  --bind <addr>                     HTTP bind address (default: 127.0.0.1:8000)\n  --max-program-buffered-bytes <N>  Global budget for all in-flight RX tools\n  --max-tool-buffered-bytes <N>     Per-tool ceiling for max_buffered_bytes\n  --profiles-path <path>            Profile store file path (default: OS user config dir + serial-mcp/profiles.toml)\n  --capture-dir <absolute-dir>      Enable persistent export_log capture into an existing absolute directory (disabled by default; no fallback to cwd/config/temp)\n  --capture-max-file-bytes <N>      Per-file quota for a capture JSONL snapshot (default: 16777216 / 16 MiB)\n  --capture-max-total-bytes <N>     Total-byte quota across committed capture files (default: 268435456 / 256 MiB)\n  --capture-max-files <N>           File-count quota across committed capture files (default: 256)\n  -V, --version                     Print version and exit (also: `serial-mcp version`)\n  -h, --help                        Print help\n\n  RUST_LOG                   Log level env var (error/warn/info/debug/trace)\n```\n\n</details>\n\nThe profile store is one TOML file shared by every session. Use `--profiles-path`\nfor an isolated store. See [Device profiles](docs/guides/device-profiles.md).\n\n### Persistent capture\n\n`export_log` writes portable `.jsonl` filenames into the `--capture-dir` root.\nIt never accepts arbitrary paths and never overwrites files. See [Persistent\ncapture](docs/guides/persistent-capture.md).\n\n## MCP compatibility\n\nserial-mcp supports MCP `2025-11-25`. This version uses the legacy session\nlifecycle.\n\nIt also supports MCP `2026-07-28`. This version uses modern discovery and\nstateless requests with SEP-2549 cache fields. Both stdio and HTTP transports\nsupport the port allowlist.\n\nCI runs official conformance checks and Inspector interoperability checks. The\nvalidation tools come from the committed npm lockfile. CI installs them with\n`npm ci --ignore-scripts`. It runs them as local binaries, never through npx.\n\nAn actual historical `rmcp 1.7.0` client tests backward compatibility over HTTP\nand stdio. Run the complete local and CI version gate with:\n\n```bash\nbash scripts/test-mcp-compat.sh\n```\n\n## Development\n\nBefore pushing or opening a pull request, run `cargo fmt --all`. CI runs\n`cargo fmt --all -- --check` once in standalone Ubuntu format job first.\nFormatting failures block dependent expensive Nix, build/test/Clippy, and MCP\nconformance jobs.\n\n```bash\ncargo test --locked\ncargo clippy --all-targets --locked -- -D warnings\ncargo fmt --all -- --check\n\n# Linux-only required Rust PTY fixture suites\ncargo test --locked --test device_fixture -- --test-threads=1\ncargo test --locked --test device_command_parity -- --test-threads=1\ncargo test --locked --test device_framing_parity -- --test-threads=1\ncargo test --locked --test device_protocol_parity -- --test-threads=1\ncargo test --locked --test device_parity_repeat public_boundary_repeat_gate -- --ignored --test-threads=1\n```\n\nProduction-path real-PTY fixture tests run on Linux. macOS and Windows run\nnormal Rust build/test/clippy plus controlled-backend coverage.\n\n## Documentation and status\n\nThe [product backlog](docs/product/README.md) tracks planned and in-progress\nwork, and the [documentation index](docs/README.md) links user guides,\nreference contracts, and reports.\nReport issues and feature requests on the [tracker](https://github.com/qarnet/serial-mcp/issues).\n\n- [CHANGELOG.md](CHANGELOG.md)\n- [AGENTS.md](AGENTS.md), contributor guidelines\n\n## MCP registry\n\nThe package is available on the [MCP Registry](https://registry.modelcontextprotocol.io/)\nas:\n\nmcp-name: io.github.qarnet/serial-mcp\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 12800,
  "sha": "2eeb903bbb15964cf3e6b7121d6fe2877f5fb1105f4f16cfe47d569f86234a6b",
  "repo_slug": "qarnet/serial-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_qarnet_serial_mcp_cc375173/readme"
}