UART MCP Server

English | 中文

为 AI 助手提供串口通信能力的 MCP Server。

功能特性

• 串口管理 - 枚举、打开、关闭和配置串口设备
• 数据通信 - 支持文本和二进制模式的数据收发
• 终端会话 - 创建交互式终端会话，支持命令发送和输出读取
• 热配置 - 支持在不关闭串口的情况下修改配置参数
• 自动重连 - 设备断开后自动尝试重新连接

快速开始

提示词配置

为了让 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"]
    }
  }
}

可用工具

串口管理

工具	描述
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	清空会话输出缓冲区

串口权限

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

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 端口默认可访问。

使用示例

基础串口通信

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

终端会话模式

1. 使用 open_port 打开串口
2. 使用 create_session 创建终端会话
3. 使用 send_command 发送命令
4. 使用 read_output 读取命令输出
5. 使用 close_session 关闭会话

串口配置参数

参数	默认值	可选值
波特率	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/

系统要求

• Python 3.13+
• 支持的操作系统: Linux, macOS, Windows

许可证

MIT License