serial-mcp-server

Serial MCP 服务

一个有状态的串口 Model Context Protocol（MCP）服务，适用于开发者工具和 AI Agent。 开箱即用，兼容 Claude Code、带 Copilot 的 VS Code，以及任何兼容 MCP 的运行时。通过 stdio 通信，并使用 pyserial 在 macOS、Windows 和 Linux 上实现跨平台串口通信。

示例： 让 Claude Code 列出可用串口、连接到微控制器、通过 DTR 重置设备，并读取硬件的启动横幅。

演示

视频演示 — 连接串口设备、发送命令、读取响应并创建插件。

---

为什么要做这个

如果你曾经把命令复制粘贴到 screen 或 minicom 中、猜测波特率、切换 DTR 来触发引导加载程序，并反复运行相同的测试序列 20 次，那么这个项目就是为你准备的。

你有一个串口设备，想让 AI Agent 与它通信——打开端口、发送命令、读取响应、调试协议。这个服务让这一切成为可能。

它为任何兼容 MCP 的 Agent 提供一整套串口工具：列出端口、打开连接、读取、写入、面向行的 I/O、控制线操作，以及协议规范和设备插件，让 Agent 能够推理更高层的设备行为，而不只是处理原始字节。

Agent 调用这些工具，获取结构化 JSON 并据此判断下一步操作，无需你为每个步骤都手动在终端中输入命令。

Agent 可以用它做什么：

• 开发和调试 — 连接设备、发送命令、读取响应，并通过对话诊断问题（启动横幅、提示符、错误代码）。
• 迭代新固件 — 附加协议规范，让 Agent 随着命令集、启动模式和输出格式的演变理解它们。
• 自动化测试流程 — 通过 DTR 重置设备、等待提示符、运行命令序列并验证输出。
• 探索未知设备 — 探测命令集、发现提示符、推断消息格式。
• 构建串口自动化 — 长时间运行的测试架、制造环节的初始调试、CI 硬件冒烟测试。

---

适用对象

• 嵌入式工程师 — 更快迭代串口协议、通过对话调试、自动执行测试序列
• 爱好者和创客 — 无需编写样板代码即可与串口设备交互；让 Agent 帮助逆向分析简单协议
• QA 和测试工程师 — 使用插件工具构建可重复的串口测试套件
• 支持和现场工程师 — 无需专用工具即可交互式诊断串口设备问题
• 研究人员 — 自动收集串口设备的数据，系统地探索设备功能

---

快速开始（Claude Code）

pip install serial-mcp-server

# Register the MCP server with Claude Code
claude mcp add serial -- serial_mcp

然后在 Claude Code 中尝试：

“列出可用串口，并以 115200 波特率连接到 /dev/ttyUSB0 上的串口。”

---

Agent 可以做什么

连接后，Agent 即拥有完整的串口操作能力：

• 列出端口，查找可用的串口设备
• 打开和关闭连接，并配置波特率、校验位、停止位和编码
• 以文本、十六进制或 base64 格式读取和写入数据
• 面向行的 I/O——对文本协议执行 readline 和按分隔符读取
• 控制线路——设置或脉冲触发 DTR 和 RTS，以重置硬件并进入引导模式
• 刷新输入和输出缓冲区
• 附加协议规范，以理解特定设备的命令和数据格式
• 使用插件执行高级设备操作，而非直接读取／写入原始数据
• 为新设备创建规范和插件，让后续会话一开始就“了解”你的协议
• PTY 镜像——让 screen、minicom 或自定义脚本连接到 Agent 使用的同一串口会话

Agent 可以自动协调多步骤流程，例如切换重置状态、等待提示符、发送初始化序列、流式输出。

总体而言：

原始串口 → 协议规范 → 插件

你可以先使用原始串口工具，随着设备协议逐渐明晰并变得可重复，再逐步深入工具栈。

---

安装（开发）

# Editable install from repo root
pip install -e .

# Or with uv
uv pip install -e .

MCP 是一种协议——此服务适用于任何兼容 MCP 的客户端。下面列出了几种常见客户端的设置说明。

添加到 Claude Code

# Standard setup
claude mcp add serial -- serial_mcp

# Or run as a module
claude mcp add serial -- python -m serial_mcp_server

# Enable all plugins
claude mcp add serial -e SERIAL_MCP_PLUGINS=all -- serial_mcp

# Enable specific plugins only
claude mcp add serial -e SERIAL_MCP_PLUGINS=mydevice,ota -- serial_mcp

# Debug logging
claude mcp add serial -e SERIAL_MCP_LOG_LEVEL=DEBUG -- serial_mcp

添加到 VS Code / Copilot

将以下内容添加到项目的 .vscode/mcp.json 中（或新建该文件）：

{
  "servers": {
    "serial": {
      "type": "stdio",
      "command": "serial_mcp",
      "args": [],
      "env": {
        "SERIAL_MCP_PLUGINS": "all"
      }
    }
  }
}

根据需要调整 env——将 SERIAL_MCP_PLUGINS 设置为特定插件名称，或添加 SERIAL_MCP_MIRROR 以启用 PTY 镜像。

添加到 Cursor

将以下内容添加到项目的 .cursor/mcp.json 中（或新建该文件）。Cursor 不支持工具名称中包含点，因此必须将 SERIAL_MCP_TOOL_SEPARATOR 设置为 _：

{
  "mcpServers": {
    "serial": {
      "command": "serial_mcp",
      "args": [],
      "env": {
        "SERIAL_MCP_PLUGINS": "all",
        "SERIAL_MCP_TOOL_SEPARATOR": "_"
      }
    }
  }
}

环境变量

变量	默认值	描述
SERIAL_MCP_MAX_CONNECTIONS	10	可同时打开的串口连接数上限。
SERIAL_MCP_PLUGINS	disabled	插件策略：设置为 all 以允许所有插件，或设置为 name1,name2 以允许指定插件。未设置时禁用。
SERIAL_MCP_MIRROR	off	PTY 镜像模式：off、ro（只读）或 rw（读写）。仅适用于 macOS 和 Linux。
SERIAL_MCP_MIRROR_LINK	/tmp/serial-mcp	PTY 符号链接的基础路径。连接会按编号命名：/tmp/serial-mcp0、/tmp/serial-mcp1 等。
SERIAL_MCP_LOG_LEVEL	WARNING	Python 日志级别（DEBUG、INFO、WARNING、ERROR）。日志会输出到 stderr。
SERIAL_MCP_TRACE	enabled	对每次工具调用进行 JSONL 跟踪。设置为 0、false 或 no 可禁用。
SERIAL_MCP_TRACE_PAYLOADS	disabled	在跟踪的参数中包含写入的 data（默认会去除）。
SERIAL_MCP_TRACE_MAX_BYTES	16384	截断前的最大负载字符数（仅在启用 TRACE_PAYLOADS 时生效）。
SERIAL_MCP_TOOL_SEPARATOR	.	用于分隔工具名称各部分的字符。对于拒绝工具名称中包含点的 MCP 客户端（例如 Cursor），请设置为 _。

---

工具

类别	工具
串口核心	serial.list_ports、serial.open、serial.close、serial.connection_status、serial.read、serial.write、serial.readline、serial.read_until、serial.flush、serial.set_dtr、serial.set_rts、serial.pulse_dtr、serial.pulse_rts
自省	serial.connections.list
协议规范	serial.spec.template、serial.spec.register、serial.spec.list、serial.spec.attach、serial.spec.get、serial.spec.read、serial.spec.search
跟踪	serial.trace.status、serial.trace.tail
插件	serial.plugin.template、serial.plugin.list、serial.plugin.reload、serial.plugin.load

---

协议规范

规范是描述串行设备协议的 Markdown 文件，包括连接设置、消息格式、命令和多步流程。它们存放在 .serial_mcp/specs/ 中，帮助 Agent 理解字节流的含义。

没有规范，Agent 仍然可以打开端口并交换数据。有了规范，它就知道要发送哪些命令、应期待哪些响应，以及数据的含义。

你可以向 Agent 介绍设备来创建规范——粘贴数据手册、描述协议，或者让它自行探索并记录发现的内容。Agent 会生成规范文件、注册该文件，并在后续会话中引用它。你也可以手动编写规范。

---

插件

插件会为服务添加特定于设备的快捷工具。插件提供高级操作（例如 mydevice.read_temp 或 ota.upload_firmware），而不是让 Agent 自行组合原始读写序列。

Agent 也可以生成 Python 插件（需经你批准）。它会探索设备，根据所了解的信息编写插件，之后的会话就能使用快捷工具——无需手动编写代码。

启用插件：

# Enable all plugins
claude mcp add serial -e SERIAL_MCP_PLUGINS=all -- serial_mcp

# Enable specific plugins only
claude mcp add serial -e SERIAL_MCP_PLUGINS=mydevice,ota -- serial_mcp

编辑已加载的插件只需调用 serial.plugin.reload，无需重启。

---

跟踪

每次工具调用都会被跟踪到 .serial_mcp/traces/trace.jsonl 和内存中的环形缓冲区（最近 2000 个事件）。跟踪功能默认开启——设置 SERIAL_MCP_TRACE=0 即可禁用。

事件格式

每次工具调用对应两个事件：

{"ts":"2025-01-01T00:00:00.000Z","event":"tool_call_start","tool":"serial.read","args":{"connection_id":"s1"},"connection_id":"s1"}
{"ts":"2025-01-01T00:00:00.050Z","event":"tool_call_end","tool":"serial.read","ok":true,"error_code":null,"duration_ms":50,"connection_id":"s1"}

• 存在 connection_id 时，会从参数中提取该值
• 默认情况下，跟踪参数中会移除写入的 data（设置 SERIAL_MCP_TRACE_PAYLOADS=1 可启用）

检查跟踪记录

使用 serial.trace.status 查看配置和事件数量，使用 serial.trace.tail 获取近期事件——无需直接读取文件。

---

PTY 镜像

当 MCP 服务占用串行端口时，大多数操作系统会阻止其他进程打开该端口。PTY 镜像会创建一个虚拟克隆端口，外部工具（screen、minicom、逻辑分析仪、自定义脚本）可以同时连接该端口。

# Enable read-only mirror
claude mcp add serial \
  -e SERIAL_MCP_MIRROR=ro \
  -- serial_mcp

# After opening a connection, the response includes the mirror path:
# { "mirror": { "pty_path": "/dev/ttys004", "link": "/tmp/serial-mcp0", "mode": "ro" } }

# In another terminal:
screen /tmp/serial-mcp0 115200

模式	行为
off	不创建镜像（默认）。只有 MCP 服务可以访问该端口。
ro	外部工具可以查看所有串行数据，但不能向设备写入数据。
rw	外部工具既可以查看数据，也可以向设备写入数据。

**平台：**仅限 macOS 和 Linux。在 Windows 上，将 SERIAL_MCP_MIRROR 设置为 ro/rw 会记录一条警告，并静默忽略该设置。

---

不使用 Agent 试用

你可以使用 MCP Inspector 交互式测试服务——无需 Claude 或其他 Agent：

npx @modelcontextprotocol/inspector python -m serial_mcp_server

使用终端输出中的身份验证令牌打开该 URL。Inspector 提供网页界面，可用于调用任何工具并实时查看响应。

---

已知限制

• **仅支持单客户端。**服务一次只处理一个 MCP 会话（stdio 传输）。未来可能会添加多客户端传输（HTTP/SSE）。
• **独占访问。**不使用 PTY 镜像时，MCP 服务必须独占串行端口。

---

安全

此服务可将 AI Agent 连接到真实硬件。这正是它的用途，也意味着风险高于纯软件工具。

插件会执行任意代码。 启用插件后，Agent 可以在你的机器上以完整的服务权限创建并运行 Python 代码。加载 Agent 生成的插件前，请先进行审查。使用 SERIAL_MCP_PLUGINS=name1,name2 仅允许特定插件，而不是 all。

写入会影响真实设备。 向串行设备发送错误命令可能触发意外行为、干扰其他已连接系统，或造成硬件损坏（例如擦除闪存、进入引导加载程序模式、触发执行器）。请考虑 Agent 能访问哪些设备。

谨慎使用工具审批。 当 MCP 客户端提示你批准工具调用时，请考虑是仅允许一次，还是始终允许。“始终允许”虽然方便，但意味着 Agent 无需进一步确认即可重复执行该操作。

本软件按“原样”提供，遵循 MIT License。对于 Agent 对你的硬件所做的操作，你须自行负责。

---

许可证

本项目遵循 MIT License，详情请见 LICENSE。

致谢

本项目基于优秀的 pyserial 库构建，用于在 Python 中实现跨平台串行通信。