JinDaGe - uart-mcp MCP Details

article

README

🚀 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/

系统要求

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

📄 许可证

MIT License

uart-mcp