UART MCP Server

UART MCP Server

English | 中文

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

功能特性

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

快速开始

提示词配置

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

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

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

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

使用示例

基础串口通信

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 关闭会话

串口配置参数

配置文件

UART MCP 的配置文件位于：

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

配置文件说明

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