UART MCP Server

# UART MCP Server [English](README_EN.md) | 中文 为 AI 助手提供串口通信能力的 MCP Server。 [](https://www.python.org/) [](https://modelcontextprotocol.io/) [](LICENSE) ## 功能特性 - **串口管理** - 枚举、打开、关闭和配置串口设备 - **数据通信** - 支持文本和二进制模式的数据收发 - **终端会话** - 创建交互式终端会话，支持命令发送和输出读取 - **热配置** - 支持在不关闭串口的情况下修改配置参数 - **自动重连** - 设备断开后自动尝试重新连接 ## 快速开始 ### 提示词配置 为了让 AI 助手优先使用 UART 工具操作串口，建议在项目提示词文件中添加以下内容： ```markdown 始终使用 uart MCP 工具进行串口操作，包括列出串口、打开/关闭串口、发送/接收数据等。 ``` 不同工具的提示词文件位置： | 工具 | 提示词文件 | |------|----------| | Claude Code | `CLAUDE.md` 或 `.claude/settings.json` | | Factory Droid | `AGENTS.md` 或 `.factory/droids/` | | Cursor | `.cursor/rules/` | | Windsurf | `.windsurfrules` | ### Claude Code ```bash claude mcp add uart -- uvx --from git+https://github.com/donnel666/uart-mcp.git uart-mcp ``` ### Codex CLI 在 `~/.codex/config.toml` 中添加： ```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` 中添加： ```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` ```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:** ```bash # 方法1：临时赋予权限 sudo chmod 777 /dev/ttyUSB0 # 方法2：将用户加入 dialout 组（推荐，重新登录后生效） sudo usermod -aG dialout $USER ``` **macOS:** ```bash # 将用户加入 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 示例 ```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 示例 ```conf # 黑名单配置（每行一个规则） # 支持精确匹配和正则表达式 # 精确匹配 /dev/ttyS0 # 正则表达式匹配所有 COM 端口 COM[0-9]+ ``` **注意：** 配置文件权限应为 600（仅所有者可读写），否则会报权限错误。 ## 本地开发 ```bash # 克隆仓库 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