Serial MCP

基于 MCP 协议的本地串口通信服务，内置实时 Web 监控面板。通过自然语言让 AI 助手与单片机、嵌入式设备直接对话。

功能特性

• 🖥️ MCP 支持 — 通过 Model Context Protocol 与 AI 客户端无缝集成
• 🔌 串口控制 — 自动扫描、连接、读写串口设备
• 🌐 Web 监控面板 — 内置 HTTP + WebSocket 双端口服务，浏览器实时旁路监控，支持手动干预

可用工具

安装运行

uv sync
uv run spes-serial-mcp

客户端配置

方式一：一键安装（推荐）

在终端执行（需已安装 uv）：

claude mcp add --scope user spes-serial-mcp -- uvx --from spes-serial-mcp spes-serial-mcp

执行后重启 Claude Code 会话生效，可用 claude mcp list 验证连接状态。

方式二：让 AI 自动添加

把下面的提示词发给 AI，即可自动完成安装配置：

请安装并配置 MCP 串口工具 spes-serial-mcp：
1. 执行 claude mcp add --scope user spes-serial-mcp -- uvx --from spes-serial-mcp spes-serial-mcp
2. 执行 claude mcp list 确认该服务状态为 connected
3. 完成后告诉我：需要重启 Claude Code 会话才能生效

快速开始

请使用串口工具，连接到我的开发板并且测试通信

启动后，AI 会自动执行以下初始化检查：

1. start_monitor_ui    → 启动 Web 面板 http://localhost:8080
2. list_ports          → 发现 COM3 等串口
3. connect_port        → 连接设备（115200）
4. write_data("hello") → 测试通信
5. read_data()         → 读取串口输入

在浏览器中打开 http://localhost:8080，你可以：

• 🔘 手动控制串口连接/断开
• 💬 实时查看 LLM 与单片机的全部对话
• ✏️ 手动下发命令（旁路干预）

Web 面板使用说明

面板不会随 MCP 服务自动启动。MCP 服务本身只通过 stdio 运行，不监听任何 HTTP 端口；只有显式调用 start_monitor_ui 工具后，才会监听 8080 端口（WebSocket 端口为 8081，页面自动连接）。

对 AI 说以下指令即可启动：

启动监控面板

也可以指定其他端口，例如：

启动监控面板，使用端口 9090

（此时 HTTP 端口为 9090，WebSocket 自动使用 9091）

启动成功后 AI 会返回链接，再用浏览器访问即可。常见问题：

• 浏览器提示「无法访问此页面」：面板尚未启动，请先让 AI 执行 start_monitor_ui
• 8080 端口被占用：换一个端口启动即可
• 面板何时关闭：面板运行在 MCP 服务进程的后台线程中，AI 客户端（Claude Code 等）退出后随之关闭

Web面板功能

面板由顶栏状态区、设备连接管理、串口监视器三个区域组成：

顶栏状态区

• 串口状态胶囊 — 实时显示连接状态（端口 · 波特率），点击即可连接/断开串口
• 主题切换 — 浅色/深色主题一键切换，选择记忆在浏览器中
• WebSocket 状态 — 显示与 MCP 服务的连接状态，断线后每 3 秒自动重连，点击可手动重连

设备连接管理

• 端口下拉框 — 点击时实时扫描本机串口，显示设备描述
• 波特率选择 — 支持 9600 ~ 921600 常用波特率，默认 115200
• 连接/断开按钮 — 连接后自动锁定端口与波特率设置，断开后恢复可选

串口监视器

• 实时日志 — 每条记录包含「时间戳 | 方向 | 来源 | 内容」四列，自动滚屏跟随最新数据；向上翻阅时暂停滚动，点击右下角按钮回到底部

• 来源分类 — 通过彩色标签区分数据来源：

  标签	方向	说明
  AI 发出	TX	LLM 通过 MCP 工具写入串口的数据
  手动发送	TX	在面板中手动下发的命令
  下位机返回	RX	单片机等设备上报的数据
  系统	SYS	连接/断开等系统消息

• TX/RX 计数 — 实时统计累计收发次数

• 保存LOG — 一键将当前日志导出为 txt 文件，文件名形如 serial-log-20260825-153000.txt

• 清空缓存 — 一键清空日志显示

手动发送（旁路干预）

• 输入框输入命令后按 Enter 或点击「立即发送」下发；↑↓ 键可切换历史命令（保留最近 50 条）
• 手动发送的命令会同步记录到 LLM 的读取缓冲区：AI 调用 read_data 时会优先返回你的干预记录与下位机回应，实现人机协作调试