ser2mcp

简体中文 | English

UART 串口 MCP 服务器：把本地串口设备封装成标准的 MCP (Model Context Protocol) 工具，让 AI 助手（Claude Desktop、Cursor 及任何 MCP 客户端）直接读写串口。

flowchart LR
    client["MCP 客户端<br>（AI 助手）"]
    server["ser2mcp<br>（后台读线程+环形缓冲）"]
    uart["UART 设备<br>（TX-RX）"]

    client <==>|"JSON-RPC over stdio"| server
    server <==>|"串口"| uart

特性

• 9 个 MCP 工具：枚举端口、打开、运行时重配置、写、读、写+读、状态、清缓冲、关闭
• 完善的串口参数配置：波特率 / 数据位(5-8) / 校验位(none/even/odd) / 停止位(1,2) / 流控(none/software/hardware) / 读超时，均可在 uart_open / uart_configure 中指定
• 内部参数可配置：环形缓冲大小 buffer_size（默认 1 MiB）、空闲判定 idle_ms、单次拉取上限 max_bytes、总超时 timeout_ms、读线程超时 read_timeout_ms（默认 500ms，仅作读安全上限，不影响延迟）
• 事件驱动/非阻塞读线程（平台适配层）：Unix（Linux/macOS）用 poll(2) + 自建管道事件驱动；Windows 用 1ms 轮询 + bytes_to_read() 门控 + timeBeginPeriod(1)，仅在数据就绪时 read()，读写延迟不再受读超时参数影响
• 上行数据不丢不堵：后台读线程持续把串口数据囤积进环形缓冲；写满后覆盖最旧数据并累计溢出计数，返回值带 overflow_delta / overflow_total，数据缺口可检测
• 二进制安全：数据以 hex 字符串传递（如 "41 54 0D 0A"），mode="text" 可切换 UTF-8 文本
• 单二进制交付：cargo build --release 产出单个可执行文件，Windows / Linux / macOS 均无需额外运行时

快速安装

也可以直接从 Releases 下载对应平台的预编译二进制（Windows / Linux / macOS）。

# 1. 拉取仓库
git clone https://github.com/woooooooooolf/ser2mcp.git
cd ser2mcp

# 2. Linux 系统依赖（仅 Debian/Ubuntu 需要；macOS/Windows 跳过）
sudo apt-get install -y libudev-dev

# 3. 构建 release 二进制
cargo build --release
# 产物：target/release/ser2mcp（Windows 下为 ser2mcp.exe）

# 4. 自检（可选）：枚举本机串口
target/release/ser2mcp --list-ports

# 5. 注册为 MCP server（见下方「接入 MCP 客户端」）