串口服务器

串行MCP服务器

用于开发人员工具和AI代理的有状态串行端口模型上下文协议（MCP）服务器。 使用Claude Code、带有Copilot的VS Code和任何兼容MCP的运行时即可开箱即用。通过以下方式进行沟通 标准 并使用 pyserial 适用于macOS、Windows和Linux上的跨平台串行。

例子： 让Claude Code列出可用的串行端口，连接到您的微控制器，通过DTR重置它，并从硬件中读取引导横幅。

演示

视频演练 --连接到串行设备、发送命令、读取响应和创建插件。

为什么存在

如果您曾经将粘贴的命令复制到 screen 或 minicom，猜测波特率，切换DTR以启动引导加载程序，并重新运行相同的测试序列20次——这是为您准备的。

你有一个串行设备。你需要一个AI代理与它通信——打开端口、发送命令、读取响应、调试协议。这台服务器使这成为可能。

它为任何兼容MCP的代理提供了一整套串行工具：列出端口、打开连接、读取、写入、面向线路的I/O、控制线操作，以及协议规范和设备插件，因此代理可以推断更高级别的设备行为，而不仅仅是原始字节。

代理调用这些工具，返回结构化JSON，并解释下一步该做什么——无需为每一步手动在终端中键入命令。

代理商可以用它做什么：

• 开发和调试 --连接到您的设备，发送命令，读取响应，并以对话方式诊断问题（引导横幅、提示、错误代码）。
• 迭代新固件 --附加协议规范，以便代理在命令集、引导模式和输出格式发生变化时理解它们。
• 自动化测试流程 --通过DTR重置设备，等待提示，运行命令序列，验证输出。
• 探索未知设备 --探测命令集、发现提示、推断消息格式。
• 构建串行自动化 --长时间运行的测试台、制造调试、CI硬件冒烟测试。

这是给谁的？

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

快速入门（克劳德代码）

pip install serial-mcp-server

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

然后在Claude Code中，尝试：

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

代理人能做什么

连接后，代理具有完整的串行功能：

• 列出端口 查找可用的串行设备
• 开和关 具有可配置波特率、奇偶校验、停止位和编码的连接
• 读写 文本、十六进制或base64格式的数据
• 面向线路的I/O --文本协议的readline和read-tuntil分隔符
• 控制线 --设置或脉冲DTR和RTS，用于硬件重置和启动模式进入
• 冲洗 输入和输出缓冲器
• 附上协议规范 了解设备特定的命令和数据格式
• 使用插件 用于高级设备操作，而不是原始读/写
• 创建规格和插件 对于新设备，以便未来的会话开始“了解”您的协议
• PTY镜像 --将screen、minicom或自定义脚本附加到代理正在使用的同一串行会话

代理可以自动协调多步流，例如切换重置、等待提示、发送初始化序列、流输出。

在高层次上：

原始序列号→ 协议规范→ 插件

您可以从原始串行工具开始，然后随着设备协议的理解和可重复性而向上移动。

安装（开发）

# Editable install from repo root
pip install -e .

# Or with uv
uv pip install -e .

MCP是一种协议，该服务器可与任何兼容MCP的客户端配合使用。以下是最常见的设置说明。

添加到克劳德代码

# 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代码/副本

添加到您的项目 .vscode/mcp.json （或创建它）：

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

调整 env 以满足您的需求--set SERIAL_MCP_PLUGINS 添加到特定插件名称，或添加 SERIAL_MCP_MIRROR 用于PTY镜像。

添加到光标

添加到您的项目 .cursor/mcp.json （或创建它）。光标不支持工具名称中的点，因此 SERIAL_MCP_TOOL_SEPARATOR 必须设置为 _:

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

环境变量

工具

协议规范

规范是描述串行设备协议的标记文件，包括连接设置、消息格式、命令和多步流。他们住在 .serial_mcp/specs/ 并教导代理字节流的含义。

如果没有规范，代理仍然可以打开端口并交换数据。有了规范，它就知道要发送什么命令、期望什么响应以及数据意味着什么。

您可以通过告诉代理您的设备来创建规范——粘贴数据表、描述协议，或者让它探索并记录它所发现的内容。代理生成规范文件，注册它，并在未来的会话中引用它。你也可以手写规格。

插件

插件将特定于设备的快捷工具添加到服务器。插件提供高级操作，如 mydevice.read_temp 或 ota.upload_firmware.

代理人还可以 生成 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个事件）。追踪是 默认开启 --set 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 当存在时，从args中提取
• 写 data 默认情况下从跟踪参数中删除（启用 SERIAL_MCP_TRACE_PAYLOADS=1)

检查痕迹

使用 serial.trace.status 检查配置和事件计数，以及 serial.trace.tail 检索最近的事件——不需要直接读取文件。

PTY后视镜

当MCP服务器拥有一个串行端口时，大多数操作系统会阻止任何其他进程打开它。PTY镜像创建了一个虚拟克隆端口，外部工具（屏幕、微型计算机、逻辑分析仪、自定义脚本）可以同时连接到该端口。

# 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

平台： 仅限macOS和Linux。在Windows上，设置 SERIAL_MCP_MIRROR 到 ro/rw 记录一个警告，并被默默忽略。

尝试不使用代理

您可以使用交互方式测试服务器 MCP检查员 --不需要克劳德或其他代理人：

npx @modelcontextprotocol/inspector python -m serial_mcp_server

从终端输出中打开带有身份验证令牌的URL。Inspector为您提供了一个web UI，可以调用任何工具并实时查看响应。

已知限制

• 仅限单一客户。 服务器一次处理一个MCP会话（stdio传输）。稍后可能会添加多客户端传输（HTTP/SSE）。
• 独家访问。 如果没有PTY镜像，MCP服务器必须独占串行端口。

安全

此服务器将AI代理连接到真实硬件。这就是重点——这意味着风险高于纯软件工具。

插件执行任意代码。 启用插件后，代理可以在您的计算机上以完全服务器权限创建和运行Python代码。在加载代理生成的插件之前，请先对其进行审查。使用 SERIAL_MCP_PLUGINS=name1,name2 只允许特定的插件，而不是 all.

写入会影响真实设备。 发送到串行设备的错误命令可能会触发意外行为，扰乱其他连接的系统，或导致硬件损坏（例如，擦除闪存、进入引导加载程序模式、触发执行器）。考虑一下代理人能达到什么。

有意使用工具批准。 当您的MCP客户端提示您批准工具调用时，请考虑是只允许一次还是始终允许。“始终允许”很方便，但意味着代理人可以重复该操作而无需进一步确认。

本软件按照MIT许可证提供。您负责代理如何处理您的硬件。

许可证

此项目根据MIT许可证获得许可——请参阅 许可证 了解详情。

致谢

这个项目是建立在优秀的基础上的 pyserial Python中用于跨平台串行通信的库。