AI导哈

串口调试MCP服务器

一款串口调试MCP服务器，提供串口枚举、连接配置、读写控制、日志审计与固件提取能力，适用于在Cursor等AI编程工具中与嵌入式设备交互。

  • by mohdkey
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 mohdkey/serial_mcp

使用说明

serial-mcp

面向 Cursor 的串口调试 MCP 服务器，提供统一的工具接口管理串口连接并与嵌入式目标交互。可配合 IOT-tools/serial_terminal.py 使用，使用前请正确配置串口。

功能特性

  • 枚举串口（VID/PID、厂商信息）
  • 配置端口、波特率、数据位、校验位、停止位及编码
  • 读写、缓冲刷新、CLI 命令、自动登录
  • 会话日志、UART 录制、安全审计、固件提取
  • 兼容 Cursor MCP，通过 mcp.json 一键接入

快速开始

安装

cd D:\serial_mcp
pip install -e .

安装后默认启用 NLP 敏感词检测（jieba 分词，中英文）。

也可使用 uv pip install -e . 获得更快体验。

运行

方式一：直接运行

serial-mcp
# 或
python -m serial_mcp.server

方式二：使用 start-serial-mcp.bat（Windows）

start-serial-mcp.bat

启动模式：

选项 说明
0 退出
1 仅 MCP（稳定连接）
2 仅 UART 录制
3 MCP + UART 录制（按需连接）
K 结束占用串口的进程

所有模式在独立窗口后台运行。[K] 可释放被 PuTTY、Arduino IDE 等占用的串口。

Cursor 配置

  1. Settings → MCP Servers → Add New Server → Custom Command
  2. Command 填写 pipx run serial-mcp 或 python -m serial_mcp.server
  3. 也可在 mcp.json 中手动添加：
{
  "mcpServers": {
    "serial-mcp": {
      "command": "C:\\Python313\\python.exe",
      "args": ["-m", "serial_mcp.server"],
      "timeout": 1800,
      "cwd": "D:\\serial_mcp"
    }
  }
}

cwd 指向项目根；若有 .venv 会优先使用 venv 的 Python。

配置

配置文件 serial_mcp.config.json

项目根目录或 SERIAL_MCP_CONFIG 指向的文件：

{
  "port": "COM7",
  "baudrate": 115200,
  "connection_mode": "on_demand"
}
  • connection_mode：stable（MCP 常连）或 on_demand（请求时连接，便于与 uart_recorder 共享）
  • 使用 serial_config_info 查看、reload_serial_config 重载

可用工具

连接与配置

工具 说明
list_serial_ports 枚举串口及基础信息
detect_baudrate 启发式探测波特率
connect_serial 建立/更新串口连接
smart_connect_serial 配置优先，乱码时自动探测波特率重连
disconnect_serial 关闭连接
serial_connection_info 查看连接状态与连接模式
set_connection_mode_stable / set_connection_mode_on_demand 切换连接模式
serial_config_info 查看配置
reload_serial_config 重载配置

读写与控制

工具 说明
write_serial 写入文本或十六进制
read_serial 读取字节或直到换行
read_until_serial 读取直到指定分隔符（AT 指令等）
flush_serial_buffers 清空缓冲
serial_cli_command 发送命令并等待响应，支持 U-Boot/Shell 自动识别
serial_login 基于 login:/password: 自动登录
set_serial_control_lines 动态拉高/拉低 DTR、RTS
pulse_dtr / pulse_rts 脉冲控制线（复位、bootloader）
delay 等待指定秒数

日志与审计

工具 说明
list_session_logs 按时间倒序浏览会话日志
analyze_security_audit 对 session/uart 日志做敏感信息检测
gather_uart_log_info 搜集 UART 日志信息（型号、操作、协议）
save_audit_report 将报告保存到 report/
serial_help 返回工具摘要与典型流程

固件提取

工具 说明
get_firmware_extraction_workflow 获取 U-Boot/Linux 固件提取工作流
extract_firmware_via_http 优先：设备 Python HTTP 服务 + 本机 wget 下载，需设备有 Python 且文件已在 /tmp
extract_firmware_via_nc 备选：nc 直传 MTD 分区，需设备有 nc 且与本机同网段

使用示例

CLI 交互

tool: serial_cli_command
args:
  command: "help"
  settle_time: 0.5
  max_bytes: 2048
  wait_for_prompt: "aic>"
  • 不传 command 时默认发送回车唤醒
  • terminal_mode: "uboot" 可适配 U-Boot
  • CLI 对输入节奏敏感时可设置 autopace（ms）

自动登录

await serial_login(username="root", password="your_password")

详细说明见 docs/SERIAL_LOGIN.md。

固件提取

优先 HTTP（设备有 Python，本机 wget 拉取，无需监听端口）：

# 先执行: dd if=/dev/mtdblock0 of=/tmp/boot.bin bs=1M
extract_firmware_via_http(device_ip="192.168.137.252", file_path="/tmp/boot.bin")

备选 nc（设备有 nc，与本机同网段）：

extract_firmware_via_nc(partition="mtdblock0", filename="boot.bin", device_ip="192.168.137.252")

进阶

连接模式

  • on_demand（默认）：请求时连接，结束后释放，便于与 uart_recorder 共享
  • stable：MCP 保持连接，适用于仅运行 MCP 的场景

释放被占用的串口

  • bat 中按 K，或命令行运行 python -m serial_mcp.kill_port_occupant
  • 使用 Sysinternals Handle 定位并结束占用进程

故障排查

  • Port busy：关闭其他串口工具或使用 [K]
  • 工具超时：增大 MCP 超时或减小 max_bytes
  • 编码异常：使用 return_hex=true 获取原始数据

文档

文档 说明
docs/毕业设计_架构与实现.md 毕设用：整体架构、技术栈、详细功能实现
docs/ARCHITECTURE.md 系统架构、模块划分
docs/SERIAL_LOGIN.md serial_login 详细说明
docs/DESIGN_HISTORY.md 功能完善与设计历史

课题功能概述

  • 自动登录：smart_connect_serial + serial_login，支持乱码时自动探测波特率
  • 日志与审计：session_logs/、uart_log/、analyze_security_audit、gather_uart_log_info
  • 报告输出：report/ 目录，audit_and_firmware_report Prompt 生成结构化报告
  • NLP 敏感词：默认启用 jieba 分词，中英文敏感词与疑似值检测

更新日志

0.2.3：extract_firmware_via_http（设备 Python HTTP 服务下载）；extract_firmware_via_nc 增加 local_ip/device_ip、30 秒连接超时、默认端口 9123

0.2.2：Cursor mcp.json 增加 cwd、优先 venv；extract_firmware_via_nc 支持 ncat/nc；report/ 目录与 save_audit_report

0.2.1：连接模式 stable/on_demand；bat 启动器与 kill_port_occupant

0.2.0：session_logs、资源接口、audit_and_firmware_report Prompt

许可证

MIT 协议。

相关 MCP