serial

This MCP server provides a production-ready serial port controller environment that exposes five serial tools (list_ports, open, write, read, close) via the MCP protocol. It integrates with Claude/AI assistants and supports cross-platform serial port discovery, connection management, and data encoding (UTF-8, Hex, Binary) with configurable timeouts. Once running, clients can request the available serial ports, open a chosen port with specific settings, send data, read responses with timeouts, and close the connection. The server is designed to work with real hardware such as STM32, Arduino, and ESP32 devices, and can be controlled through the MCP protocol by sending the standard tool commands to the server and receiving structured responses.

Prerequisites:

• Docker installed and running (recommended for the Docker-based setup below)
• Optional: Access to a host with serial hardware connected for testing

1. Install Docker (if not already installed)

   • Windows: https://docs.docker.com/windows/
   • macOS: https://docs.docker.com/docker-for-mac/
   • Linux: https://docs.docker.com/engine/install/

2. Run the MCP server (Docker)

   • This pulls and runs the latest serial MCP server image and exposes the MCP endpoint via the container

   docker run -i adancurusul/serial-mcp-server:latest

3. Verify the server starts correctly

   • Check the container logs for startup messages indicating MCP is listening
   • If you need to customize logging, pass an environment variable like RUST_LOG=info when running the container

4. If you prefer building from source locally (Rust/Cargo)

   • Prerequisites: Rust 1.70+ and cargo

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

   ./target/release/serial-mcp-server

5. Connect a client using MCP protocol

   • Use the MCP tooling to configure the server endpoint and start issuing commands to list ports, open a port, write data, read responses, and close the connection

Tips and notes:

• If you encounter port detection issues, ensure the serial device is connected and has appropriate permissions (on Linux/macOS, you may need to add your user to the dialout or uucp groups).
• Timeouts are configurable when using the read tool; adjust the timeout to match device response times.
• For debugging, enable verbose logs by setting RUST_LOG=info (or higher) in the environment.
• The 5 tools (list_ports, open, write, read, close) are validated against real hardware; ensure your device is powered and configured (baud rate, parity, stop bits) as expected by your application.
• If running under Docker, you may need to pass through the host's serial devices (e.g., --device /dev/ttyUSB0:/dev/ttyUSB0) depending on your container runtime and OS to access physical ports.