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