Serial MCP

用于 UART 和 USB 串行访问的 serial-mcp

serial-mcp 是一个用于直接访问串行端口的 MCP 服务。它可以读取、写入并流式传输到微控制器、Arduino 开发板、STM32 芯片及其他嵌入式目标的 UART 或 USB 串行数据。读取操作采用超时和模式匹配，而非在串行监视器上阻塞。

该服务会持续捕获 RX 数据。它使用行、分隔符、长度前缀、起始/结束、SLIP 和 COBS 格式解码 TX 和 RX 帧，并提供 AT、JSON、shell、NMEA-0183 和 Modbus ASCII 解析器。

协议预设支持校验和验证。该服务还支持自动重连、事件日志记录、DTR/RTS、BREAK 和流控。MCP 客户端可以将这些功能用于串行引导加载程序、重置和嵌入式开发板。

快速开始

1. 安装服务。请参阅安装，了解 Cargo、Nix 和预编译二进制文件选项。
2. 连接 Agent。按照 Agent 配置指南操作，或使用下方示例。
3. 发现设备。调用 list_ports() 并检查 profile_matches。结果会显示直接调用 open 时将复用的配置。
4. 打开端口。只需传入端口调用 open(port=...)。 波特率默认为 115200/8-N-1。对于已知设备，服务会复用最近使用的高置信度配置；对于新设备，则会创建持久化的自动生成配置。
5. 与设备通信。使用 transact() 进行命令与响应交互。使用 read() 读取缓冲数据或设备主动发送的数据。使用 write() 执行仅发送操作。

功能

工具目录（25 个工具）

资源和提示词

安装

Cargo（所有平台）

cargo install serial-mcp

Nix

nix profile install github:qarnet/serial-mcp

预构建二进制文件

无需工具链。每个发行版都会为每个平台发布一个二进制文件。latest/download URL 会指向最新发行版。

在 Linux 上，将你的用户添加到 dialout 组以访问端口：

sudo usermod -aG dialout $USER

连接 Agent

客户端专属的设置说明，请参阅 Agent 配置指南。 该指南涵盖 Claude Code CLI、Claude Desktop、Cursor、VS Code、Zed、opencode、 Codex、Hermes 和 HTTP 传输。

{
  "mcpServers": {
    "serial": {
      "type": "stdio",
      "command": "serial-mcp",
      "args": ["--allowlist=/dev/ttyACM*,/dev/ttyUSB*"]
    }
  }
}

核心工作流

常见操作按以下顺序进行：发现、打开、通信、验证已学习的 配置文件，然后按需使用高级工具。

1. 调用 list_ports()。其中的 profile_matches 条目与 ports 相对应。
   • selected 表示不带参数的 open 会复用 selected_profile。
   • ambiguous 表示排名相同的配置文件需要通过 open_profile 指定。
   • duplicate、ineligible 和 none 表示不带参数的 open 会从头开始或使用临时配置。
2. 调用不带参数的 open(port=...)。结果包含 profile 绑定信息。该绑定会报告其名称、来源、置信度、持久性、生成标记、修订版本和脏状态。
3. 使用 transact(data=..., match=..., timeout_ms=...) 在一次调用中写入数据并等待响应。使用 read() 读取缓冲数据或非请求数据。
4. 调用 reconfigure、set_flow_control 或连接模式的 configure 后， 检查 profile_persistence。其值为 persisted、not_needed、 transient 或 failed。同时检查更新后的 profile 绑定信息。
5. 调用 close()。为确保安全，正常关闭时会重试持久化脏绑定。

要捕获启动和重置过程，请调用 capture_boot。它可以处理 Arduino 自动重置、 电源循环横幅和启动提示。

该调用会清除未读取的操作系统输入，并标记 RX 实时边界。它可以脉冲触发 DTR/RTS， 并保证释放信号。它仅通过私有游标捕获标记之后的字节。 结果会限制在内存中，不会写入文件。from 游标模型请参阅接收与读取。 配置文件行为请参阅设备配置文件。

协议

protocol 字段为两个方向提供成帧和解析器默认值。 NMEA 和 Modbus ASCII 预设会验证校验和：

字段优先级依次为：显式调用字段、调用时预设、连接默认值， 然后是连接预设。协议指南详细说明了 此顺序、校验和行为以及成帧和解析器参考。

核心概念与指南

传输方式与选项

serial-mcp [OPTIONS]

  --transport <stdio|http>          Transport to use (default: stdio)
  --allowlist <patterns>            Comma-separated glob patterns for allowed ports
  --bind <addr>                     HTTP bind address (default: 127.0.0.1:8000)
  --max-program-buffered-bytes <N>  Global budget for all in-flight RX tools
  --max-tool-buffered-bytes <N>     Per-tool ceiling for max_buffered_bytes
  --profiles-path <path>            Profile store file path (default: OS user config dir + serial-mcp/profiles.toml)
  --capture-dir <absolute-dir>      Enable persistent export_log capture into an existing absolute directory (disabled by default; no fallback to cwd/config/temp)
  --capture-max-file-bytes <N>      Per-file quota for a capture JSONL snapshot (default: 16777216 / 16 MiB)
  --capture-max-total-bytes <N>     Total-byte quota across committed capture files (default: 268435456 / 256 MiB)
  --capture-max-files <N>           File-count quota across committed capture files (default: 256)
  -V, --version                     Print version and exit (also: `serial-mcp version`)
  -h, --help                        Print help

  RUST_LOG                   Log level env var (error/warn/info/debug/trace)

配置文件存储是一个由所有会话共享的 TOML 文件。使用 --profiles-path 指定独立存储。请参阅设备配置文件。

持久化捕获

export_log 会在 --capture-dir 根目录中写入可移植的 .jsonl 文件名。 它绝不接受任意路径，也绝不会覆盖文件。请参阅持久化捕获。

MCP 兼容性

serial-mcp 支持 MCP 2025-11-25。此版本使用旧版会话生命周期。

它还支持 MCP 2026-07-28。此版本使用现代发现机制，以及带有 SEP-2549 缓存字段的无状态请求。stdio 和 HTTP 传输均支持端口允许列表。

CI 会运行官方一致性检查和 Inspector 互操作性检查。验证工具来自已提交的 npm 锁定文件。CI 使用 npm ci --ignore-scripts 安装这些工具，并将其作为本地二进制文件运行，绝不通过 npx 运行。

实际的历史版本 rmcp 1.7.0 客户端会通过 HTTP 和 stdio 测试向后兼容性。运行完整的本地和 CI 版本门禁：

bash scripts/test-mcp-compat.sh

开发

推送或发起拉取请求前，请运行 cargo fmt --all。CI 会先在独立的 Ubuntu 格式检查任务中运行一次 cargo fmt --all -- --check。 格式错误会阻止后续耗费资源的 Nix、构建／测试／Clippy 和 MCP 一致性任务。

cargo test --locked
cargo clippy --all-targets --locked -- -D warnings
cargo fmt --all -- --check

# Linux-only required Rust PTY fixture suites
cargo test --locked --test device_fixture -- --test-threads=1
cargo test --locked --test device_command_parity -- --test-threads=1
cargo test --locked --test device_framing_parity -- --test-threads=1
cargo test --locked --test device_protocol_parity -- --test-threads=1
cargo test --locked --test device_parity_repeat public_boundary_repeat_gate -- --ignored --test-threads=1

生产路径的真实 PTY 夹具测试在 Linux 上运行。macOS 和 Windows 会运行常规 Rust 构建／测试／Clippy，以及受控后端覆盖测试。

文档与状态

产品待办事项会跟踪计划中和进行中的工作，文档索引则链接到用户指南、参考契约和报告。 请在问题跟踪器上报告问题和功能请求。

• CHANGELOG.md
• AGENTS.md，贡献者指南

MCP 注册表

此软件包已在 MCP 注册表中发布，名称为：

mcp-name: io.github.qarnet/serial-mcp

许可证

MIT。请参阅 LICENSE。