Skip to content
Back to search

serial-mcp-server

Rust MCP server and CLI for serial/UART devices, with JSON macro automation and agent skills for repeatable timed workflows.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/adancurusul--serial-mcp-server/badge.svg)](/listings/adancurusul--serial-mcp-server)

HTML

<a href="/listings/adancurusul--serial-mcp-server"><img src="/api/listings/adancurusul--serial-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/adancurusul/serial-mcp-server.git
cd serial-mcp-server
cargo build --release

The binary is built at:

target/release/serial-mcp-server

To install the CLI onto your `PATH` from a checkout:

cargo install --path . --locked

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 308 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Serial MCP Server
  2. [![Rust](https://img.shields.io/badge/rust-1.74+-orange.svg)](https://rust-lang.org)
  3. [![RMCP](https://img.shields.io/badge/RMCP-0.3.2-blue.svg)](https://github.com/modelcontextprotocol/rust-sdk)
  4. [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
  5. `serial-mcp-server` provides serial port access for AI workflows in two forms:
  6. - MCP stdio server for clients that support MCP tools.
  7. - Scriptable CLI for direct use, CI, and agent skills without MCP setup.
  8. Current release target: `0.3.0`.
  9. Language versions: [English](README.md) | [Chinese](README_ZH.md)
  10. ## 0.3.0 Update Brief
  11. - Added JSON Macro DSL automation for repeatable serial procedures.
  12. - Added CLI macro commands: `macro validate`, `macro list`, `macro plan`, and `macro run`.
  13. - Added MCP macro tools for runtime in-memory pack load/list/unload, plan, and run.
  14. - Added explicit no-hardware simulation for macro validation, planning, and executor smoke tests.
  15. - Kept Quick out of the public API. Quick-style use cases should be represented as macros.
  16. ## Macro Automation
  17. Use macros when a serial workflow is more than a single read or write. Many devices require a timed sequence: send a command, wait a few milliseconds, read until a prompt or acknowledgement appears, then send the next command. A macro pack records that procedure as JSON so a human, CLI script, or AI agent can validate it, inspect the plan, simulate it without hardware, and run it against a real port when a device is attached.
  18. Typical macro use cases:
  19. - Boot or provisioning flows that need ordered commands and delays.
  20. - Protocol handshakes that must wait for `OK`, `READY`, `PONG`, prompts, or other expected responses.
  21. - Regression smoke tests where the same serial procedure should run repeatedly.
  22. - AI-assisted debugging where the agent should review the full send/delay/expect plan before touching hardware.
  23. The v0.3 DSL is intentionally small:
  24. - `send`: write UTF-8, hex, or base64 bytes.
  25. - `delay`: wait for a fixed number of milliseconds.
  26. - `expect`: read until the response contains or equals expected bytes.
  27. - `assembly`: compose named macros into a longer workflow.
  28. AI agents can discover macro support from this README, from the bundled `skills/serial-debug` skill, by running `serial-mcp-server macro --help`, or through MCP tool discovery when the server is configured. Agents that do not use MCP can still use the CLI plus the skill docs.
  29. ## Requirements
  30. - Rust 1.74 or newer.
  31. - A serial device or USB-to-serial adapter when running hardware operations.
  32. - Device drivers and OS permissions for the selected serial port.
  33. ## Install From Source
  34. ```bash
  35. git clone https://github.com/adancurusul/serial-mcp-server.git
  36. cd serial-mcp-server
  37. cargo build --release
  38. ```
  39. The binary is built at:
  40. ```bash
  41. target/release/serial-mcp-server
  42. ```
  43. To install the CLI onto your `PATH` from a checkout:
  44. ```bash
  45. cargo install --path . --locked
  46. ```
  47. ## CLI Usage
  48. Use the CLI when you want direct serial operations without an MCP client.
  49. ```bash
  50. serial-mcp-server --help
  51. serial-mcp-server list-ports --json
  52. serial-mcp-server probe --port <port> --baud 115200 --json
  53. serial-mcp-server write --port <port> --baud 115200 --data H --read --timeout-ms 1000 --json
  54. serial-mcp-server read --port <port> --baud 115200 --timeout-ms 1000 --json
  55. serial-mcp-server read --port <port> --baud 115200 --duration-ms 5000 --initial-timeout-ms 30000 --idle-timeout-ms 1500 --json
  56. serial-mcp-server set-control-lines --port <port> --rts high --dtr low --json
  57. ```
  58. ### Capture Window Reads
  59. `timeout-ms` keeps its original one-read meaning: wait up to that many
  60. milliseconds for one read operation, then return as soon as bytes are available.
  61. Use `--duration-ms` when an AI or script needs one bounded collection window.
  62. Capture mode keeps reading internally and returns one combined response with
  63. `completion_reason`, `waited_ms`, `elapsed_ms`, and per-chunk metadata.
  64. ```bash
  65. serial-mcp-server read --port <port> --baud 115200 \
  66. --duration-ms 5000 \
  67. --start-trigger first-byte \
  68. --initial-timeout-ms 30000 \
  69. --idle-timeout-ms 1500 \
  70. --max-bytes 8192 \
  71. --json
  72. ```
  73. Capture options:
  74. - `--duration-ms`: collection window length after capture starts.
  75. - `--start-trigger first-byte`: wait for the first byte before starting the
  76. duration clock. This is the default for capture mode.
  77. - `--start-trigger immediate`: start the duration clock when the command starts.
  78. - `--initial-timeout-ms`: maximum wait for the first byte in first-byte mode.
  79. If omitted, the command uses `--timeout-ms`.
  80. - `--idle-timeout-ms`: stop after this many quiet milliseconds once capture has
  81. started.
  82. - `--max-bytes`: hard cap on the combined response bytes.
  83. `write --read` accepts the same capture options after the write:
  84. ```bash
  85. serial-mcp-server write --port <port> --baud 115200 --data RUN --read \
  86. --duration-ms 5000 --initial-timeout-ms 30000 --json
  87. ```
  88. Macro automation commands:
  89. ```bash
  90. serial-mcp-server macro validate --file examples/macros/ping.json --json
  91. serial-mcp-server macro list --file examples/macros/ping.json --json
  92. serial-mcp-server macro plan --file examples/macros/ping.json --macro ping --json
  93. serial-mcp-server macro run --file examples/macros/ping.json --macro ping --dry-run --json
  94. serial-mcp-server macro run --file examples/macros/ping.json --macro ping --simulate-read PONG --json
  95. serial-mcp-server macro run --file examples/macros/ping.json --macro ping --port <port> --baud 115200 --json
  96. ```
  97. Macro packs are JSON files with `schema_version` set to `0.3`. v0.3 supports `send`, `delay`, and `expect` steps inside macros, plus assemblies that call macros by name. `expect` supports `contains` and `equals`.
  98. The macro DSL is intentionally restricted. It does not run shell commands, JavaScript, Python, file operations, loops, variables, if/else branches, Quick commands, or RTS/DTR macro steps.
  99. Configuration commands:
  100. ```bash
  101. serial-mcp-server generate-config
  102. serial-mcp-server validate-config --config serial-mcp.toml
  103. serial-mcp-server show-config --config serial-mcp.toml
  104. ```
  105. CLI output rules:
  106. - stdout is reserved for command data and JSON.
  107. - stderr is reserved for diagnostics.
  108. - `--json` output should be parseable by tools such as `jq`.
  109. - Nonzero exit codes indicate command failure.
  110. Supported CLI data formats are `utf8`, `hex`, and `base64`. Use `hex` or `base64` for binary payloads.
  111. ## MCP Usage
  112. Use MCP when your client supports MCP tools and you want a long-running stdio server.
  113. Recommended server command:
  114. ```bash
  115. serial-mcp-server serve
  116. ```
  117. No-subcommand startup is retained as a compatibility path for existing MCP setups, but new configurations should use `serve`.
  118. Claude Desktop example for macOS/Linux:
  119. ```json
  120. {
  121. "mcpServers": {
  122. "serial": {
  123. "command": "/path/to/serial-mcp-server/target/release/serial-mcp-server",
  124. "args": ["serve"],
  125. "env": {
  126. "RUST_LOG": "info"
  127. }
  128. }
  129. }
  130. }
  131. ```
  132. Windows example:
  133. ```json
  134. {
  135. "mcpServers": {
  136. "serial": {
  137. "command": "C:\\path\\to\\serial-mcp-server\\target\\release\\serial-mcp-server.exe",
  138. "args": ["serve"],
  139. "env": {
  140. "RUST_LOG": "info"
  141. }
  142. }
  143. }
  144. }
  145. ```
  146. ## MCP Tools
  147. | Tool | Purpose |
  148. | --- | --- |
  149. | `list_ports` | Discover available serial ports. |
  150. | `open` | Open a serial connection. |
  151. | `write` | Write UTF-8, hex, or base64 data to an open connection. |
  152. | `read` | Read data from an open connection with timeout handling or a bounded capture window. |
  153. | `close` | Close an open connection. |
  154. | `set_control_lines` | Set RTS and/or DTR on an open connection. |
  155. | `macro_load` | Validate and load an inline macro pack or pack file path into the server's in-memory registry. |
  156. | `macro_list` | List loaded macro packs, macros, and assemblies. |
  157. | `macro_unload` | Remove a loaded macro pack from the in-memory registry. |
  158. | `macro_plan` | Expand a loaded, inline, or file-backed macro or assembly without opening hardware. |
  159. | `macro_run` | Run a loaded macro or assembly against an existing connection or explicit simulation input. |
  160. | `macro_run_inline` | Validate, plan, and run an inline macro pack without storing it in the registry. |
  161. The MCP macro registry is runtime-only. Restarting the server clears loaded packs, and the server does not write a persistent macro library.
  162. MCP `read` accepts these optional capture fields in addition to
  163. `connection_id`, `timeout_ms`, `max_bytes`, and `encoding`:
  164. ```json
  165. {
  166. "connection_id": "...",
  167. "duration_ms": 5000,
  168. "start_trigger": "first_byte",
  169. "initial_timeout_ms": 30000,
  170. "idle_timeout_ms": 1500,
  171. "max_bytes": 8192,
  172. "encoding": "utf8"
  173. }
  174. ```
  175. When `duration_ms` is absent, MCP `read` keeps the existing single-read
  176. behavior. When `duration_ms` is present, the tool returns structured JSON text
  177. with `completion_reason`, `waited_ms`, `elapsed_ms`, and `chunks`.
  178. ## Agent Skill
  179. The repository includes a Claude Code and Codex compatible skill at:
  180. ```text
  181. skills/serial-debug/
  182. ```
  183. The skill is CLI-first and documents MCP as an optional configured path. It is intended for agents that need to list ports, run serial smoke tests, run macro automation, control RTS/DTR, or troubleshoot UART/USB-serial devices.
  184. For local development, copy the skill folder into the agent skill roots:
  185. ```bash
  186. mkdir -p ~/.codex/skills ~/.claude/skills ~/.agents/skills
  187. cp -R skills/serial-debug ~/.codex/skills/
  188. cp -R skills/serial-debug ~/.claude/skills/
  189. cp -R skills/serial-debug ~/.agents/skills/
  190. ```
  191. Tested explicit triggers:
  192. ```text
  193. Codex: Use $serial-debug
  194. Claude Code: /serial-debug
  195. ```
  196. Claude Code `--bare` mode did not resolve `/serial-debug` in local testing; use normal Claude Code print or interactive mode for skill-trigger smoke tests.
  197. ## Hardware Safety
  198. Serial commands can affect real hardware.
  199. - Confirm the selected port from `serial-mcp-server list-ports --json`.
  200. - Confirm voltage levels before connecting an adapter to a target board.
  201. - Confirm baud rate, data bits, parity, stop bits, and flow control before writing.
  202. - Treat RTS and DTR carefully. Many boards wire those lines to reset or boot mode.
  203. - Validation claims should be based on command output from the connected device.
  204. ## STM32 Demo
  205. The STM32 demo is under:
  206. ```text
  207. examples/STM32_demo/
  208. ```
  209. It provides firmware for an interactive serial command interface. See [examples/STM32_demo/README.md](examples/STM32_demo/README.md) for wiring, firmware commands, MCP usage, and CLI smoke commands.
  210. ## Quality Gates
  211. Release work uses the checked-in `Cargo.lock` and these gates:
  212. ```bash
  213. cargo fmt --all -- --check
  214. cargo clippy --locked --all-targets --all-features -- -D warnings
  215. cargo test --locked --all-targets --all-features
  216. cargo doc --locked --all-features --no-deps
  217. ```
  218. CLI smoke:
  219. ```bash
  220. cargo run --locked -- --help
  221. cargo run --locked -- list-ports --json
  222. cargo run --locked -- write --help
  223. cargo run --locked -- set-control-lines --help
  224. cargo run --locked -- macro validate --file examples/macros/ping.json --json
  225. cargo run --locked -- macro run --file examples/macros/ping.json --macro ping --simulate-read PONG --json
  226. ```
  227. ## License
  228. This project is licensed under the MIT License. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.