Serial MCP Server

What adancurusul/serial-mcp-server MCP server does

The adancurusul/serial-mcp-server MCP server connects agent workflows to serial ports exposed by the host operating system. Its basic operations cover port discovery, connection lifecycle, data transfer, and modem-control signals. Agents can list available ports, open a connection, send bytes, receive bytes, set RTS or DTR, and close the connection.

Data can be represented as UTF-8, hexadecimal, or base64. Reads support a normal timeout-based operation and a bounded capture mode. Capture mode can wait for the first byte, collect data for a specified duration, stop after an idle interval, and enforce a maximum byte count. The returned capture information includes timing, completion details, and chunk metadata.

How it works

The server is intended to run locally over MCP stdio. A client starts the compiled serial-mcp-server executable with the serve subcommand, after which MCP tools manage connections maintained by that process. The repository also supplies a CLI for direct commands such as listing ports, reading, writing, probing, changing control lines, and producing JSON output for scripts.

For multi-step procedures, a JSON macro pack can contain named macros and assemblies. Macros use a deliberately limited set of steps: send UTF-8, hex, or base64 data; wait for a fixed delay; and expect a response that contains or equals specified bytes. Assemblies combine named macros. Plans can be inspected before hardware access, and runs can use simulated input or an existing serial connection.

Setup and configuration

The adancurusul/serial-mcp-server MCP server requires Rust 1.74 or newer. The documented source workflow clones the repository and builds a release binary with Cargo; the resulting executable is placed under target/release. It can also be installed onto the PATH from a checkout with Cargo's path-install command.

MCP clients need the executable path and the serve argument. The README includes a Claude Desktop configuration for macOS, Linux, and Windows. Hardware use additionally depends on a connected serial device or USB-to-serial adapter, suitable operating-system drivers, and permission to access the selected port.

The CLI includes commands to generate, validate, and display a TOML configuration. JSON output is available for operational commands, with standard output reserved for command data and standard error used for diagnostics.

Tools and capabilities

The MCP tool set includes:

• list_ports, open, close, write, and read for serial communication.
• set_control_lines for RTS and DTR changes.
• macro_load, macro_list, and macro_unload for managing packs in memory.
• macro_plan for expanding a macro or assembly without opening hardware.
• macro_run for execution against a connection or simulation input.
• macro_run_inline for validating, planning, and running an inline pack without registering it.

Limitations and notes

The macro registry is temporary: restarting the process removes loaded packs, and the server does not persist a macro library. The macro language does not provide shell execution, JavaScript, Python, file operations, loops, variables, conditional branches, Quick commands, or RTS/DTR macro steps. Real hardware operations require the host's serial support and permissions. The project is released under the MIT license.