uart-mcp - 支持串口管理、数据收发，为AI助手提供串口通信能力的MCP服务器

探索

Uart MCP

为AI助手提供串口通信能力的MCP服务器，支持串口管理、数据收发和终端会话等功能

开发者工具家庭自动化与物联网 #串口通信 #MCP工具 #硬件交互 #终端会话 .Python

评分 : 2.5分

下载量 : 8.1K

更新时间 : 2025-12-29

打开站点

什么是UART MCP Server?

UART MCP Server是一个专门为AI助手设计的串口通信工具。它允许AI助手（如Claude、Cursor等）直接与串口设备进行交互，就像人类工程师使用串口调试助手一样。通过这个工具，AI可以帮你调试嵌入式设备、读取传感器数据、控制硬件设备等。

如何使用UART MCP Server?

使用非常简单：1) 在你的AI工具中配置MCP服务器，2) AI助手会自动获得串口操作能力，3) 直接告诉AI你想要操作的串口设备或发送的命令，AI就会帮你完成所有技术操作。

适用场景

嵌入式开发调试、物联网设备管理、硬件设备控制、传感器数据读取、自动化测试、工业设备监控等需要与串口设备交互的场景。

主要功能

串口设备管理

自动检测和列出所有可用的串口设备，支持打开、关闭和配置串口参数

智能数据通信

支持文本和二进制模式的数据收发，AI会自动处理编码和解码

交互式终端会话

创建类似终端的环境，可以连续发送命令并读取响应，适合调试会话

热配置更新

无需关闭串口即可修改配置参数，如波特率、数据位等

自动重连机制

设备意外断开时自动尝试重新连接，确保通信连续性

跨平台支持

支持Windows、macOS和Linux系统，自动适配不同平台的串口命名规则

优势

无需学习复杂串口工具：AI帮你处理所有技术细节

自然语言交互：用说话的方式操作串口设备

自动化能力：AI可以执行复杂的调试流程

跨平台一致性：在不同操作系统上体验一致

配置简单：一次配置，多个AI工具共享

局限性

需要AI工具支持MCP协议

某些系统需要手动配置串口权限

实时性要求极高的场景可能不如专业工具

二进制数据处理需要明确指令

如何使用

配置AI工具

根据你使用的AI工具（Claude Desktop、Cursor等），在配置文件中添加UART MCP Server

设置串口权限

确保你的用户账户有权限访问串口设备（不同系统方法不同）

开始使用

重启AI工具，现在你可以用自然语言让AI操作串口了

使用案例

调试ESP32开发板

通过串口与ESP32开发板通信，发送AT命令测试Wi-Fi模块

读取Arduino传感器数据

从Arduino读取温度传感器数据并解析

自动化设备测试

自动执行一系列测试命令并记录结果

常见问题

为什么AI说没有找到串口设备？

如何发送十六进制数据？

支持哪些波特率？

数据接收不完整怎么办？

如何同时与多个串口设备通信？

🚀 UART MCP Server

UART MCP Server 是一个为 AI 助手提供串口通信能力的服务器。它可以帮助 AI 助手方便地进行串口设备管理和数据通信，支持多种功能特性，如串口管理、数据通信、终端会话等。

✨ 主要特性

串口管理：可以枚举、打开、关闭和配置串口设备，方便对串口进行操作和管理。
数据通信：支持文本和二进制模式的数据收发，满足不同类型数据的传输需求。
终端会话：能够创建交互式终端会话，支持命令发送和输出读取，实现与串口设备的交互操作。
热配置：支持在不关闭串口的情况下修改配置参数，提高配置的灵活性。
自动重连：设备断开后自动尝试重新连接，确保通信的稳定性。

🚀 快速开始

提示词配置

为了让 AI 助手优先使用 UART 工具操作串口，建议在项目提示词文件中添加以下内容：

始终使用 uart MCP 工具进行串口操作，包括列出串口、打开/关闭串口、发送/接收数据等。

不同工具的提示词文件位置如下：

工具	提示词文件
Claude Code	`CLAUDE.md` 或 `.claude/settings.json`
Factory Droid	`AGENTS.md` 或 `.factory/droids/`
Cursor	`.cursor/rules/`
Windsurf	`.windsurfrules`

Claude Code

claude mcp add uart -- uvx --from git+https://github.com/donnel666/uart-mcp.git uart-mcp

Codex CLI

在 ~/.codex/config.toml 中添加：

[mcp_servers.uart]
type = "stdio"
command = "uvx"
args = ["--from", "git+https://github.com/donnel666/uart-mcp.git", "uart-mcp"]

Factory Droid

在项目 .factory/settings.json 或全局 ~/.factory/settings.json 中添加：

{
  "mcpServers": {
    "uart": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/donnel666/uart-mcp.git", "uart-mcp"]
    }
  }
}

Claude Desktop

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "uart": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/donnel666/uart-mcp.git", "uart-mcp"]
    }
  }
}

📦 安装指南

串口权限

请确保本工具有权限访问串口设备：

Linux：

# 方法1：临时赋予权限
sudo chmod 777 /dev/ttyUSB0

# 方法2：将用户加入 dialout 组（推荐，重新登录后生效）
sudo usermod -aG dialout $USER

macOS：

# 将用户加入 wheel 组
sudo dseditgroup -o edit -a $USER -t user wheel

Windows：通常无需额外配置，COM 端口默认可访问。

💻 使用示例

基础用法

基础串口通信

使用 list_ports 查看可用串口。
使用 open_port 打开串口，如 /dev/ttyUSB0 或 COM1。
使用 send_data 发送数据。
使用 read_data 读取响应。
使用 close_port 关闭串口。

终端会话模式

使用 open_port 打开串口。
使用 create_session 创建终端会话。
使用 send_command 发送命令。
使用 read_output 读取命令输出。
使用 close_session 关闭会话。

📚 详细文档

可用工具

串口管理

工具	描述
`list_ports`	列出所有可用串口设备
`open_port`	打开指定串口（支持配置波特率、数据位、校验位等）
`close_port`	关闭指定串口
`set_config`	修改已打开串口的配置（热更新）
`get_status`	获取串口当前状态和配置信息

数据通信

工具	描述
`send_data`	向串口发送数据（支持文本/二进制模式）
`read_data`	从串口读取数据（支持文本/二进制模式）

终端会话

工具	描述
`create_session`	创建终端会话（支持配置换行符、本地回显）
`close_session`	关闭终端会话
`send_command`	向终端发送命令
`read_output`	读取终端输出缓冲区
`list_sessions`	列出所有活动会话
`get_session_info`	获取会话详细信息
`clear_buffer`	清空会话输出缓冲区

串口配置参数

参数	默认值	可选值
波特率	115200	300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800, 921600
数据位	8	5, 6, 7, 8
校验位	N (无)	N (无), E (偶), O (奇), M (标记), S (空格)
停止位	1	1, 1.5, 2
流控制	none	none, xonxoff, rtscts, dsrdtr

配置文件

UART MCP 的配置文件位于：

Linux/macOS：~/.uart-mcp/
Windows：%APPDATA%\.uart-mcp\

配置文件说明

文件	说明
`config.toml`	全局配置（波特率、超时、流控等默认参数）
`blacklist.conf`	串口黑名单（支持精确匹配和正则表达式）

config.toml 示例

[serial]
baudrate = 115200
bytesize = 8
parity = "N"
stopbits = 1.0

[timeout]
read_timeout = 1000
write_timeout = 1000

[flow_control]
xonxoff = false
rtscts = false
dsrdtr = false

[reconnect]
auto_reconnect = true
reconnect_interval = 5000

[logging]
log_level = "INFO"

blacklist.conf 示例

# 黑名单配置（每行一个规则）
# 支持精确匹配和正则表达式

# 精确匹配
/dev/ttyS0

# 正则表达式匹配所有 COM 端口
COM[0-9]+

⚠️ 重要提示

配置文件权限应为 600（仅所有者可读写），否则会报权限错误。

本地开发

# 克隆仓库
git clone https://github.com/donnel666/uart-mcp.git
cd uart-mcp

# 安装依赖
uv sync --dev

# 运行服务器
uv run uart-mcp

# 运行测试
uv run pytest

# 代码检查
uv run ruff check src/
uv run mypy src/