uart-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@uart-mcp Open /dev/ttyUSB0 at 115200 and wait for 'boot completed'."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
uart-mcp
中文
用于 UART 和串口调试的本地 Model Context Protocol (MCP) 服务端。它通过基于换行符分隔的标准输入输出 (stdio) 提供 MCP 服务,适用于运行在能够直接访问串口转接器的本机环境中。
功能特性
持久捕获会话:内置有界的内存环形缓冲区(Ring Buffer)和按天滚动的日志文件。
数据读取与监控:支持读取新增捕获行、等待正则/事件匹配、查看近期输出以及检索历史日志。
端口与交互:支持枚举可用串口,并支持单次 HEX 数据的发送/应答(query)交互。
协议解析:支持根据 YAML 协议描述文件解析捕获的 HEX 数据。
Shell 自动化交互:支持向类 Shell 交互的终端设备依次执行一系列串口命令。
跨平台支持:基于 Python 和 pySerial 实现,具备跨平台兼容性。
环境要求
Python 3.10 或更高版本。
串口转接器/适配器以及使用该硬件设备所需的操作系统级权限。
uv(推荐)或pip。
安装与运行
克隆代码仓库,并在隔离环境中安装运行:
uv sync
uv run uart-mcp该服务端采用 MCP stdio 协议。MCP 客户端会将其作为子进程启动,并通过 stdin/stdout 交换 JSON-RPC 消息。诊断信息输出至 stderr,确保 stdout 专用于协议传输。
或者,使用 pip 安装并运行命令行:
python -m pip install .
uart-mcp开发与测试:
uv sync --group dev
uv run pytest自动化测试使用模拟串口设备(fake serial device),无需连接真实硬件。
MCP 客户端配置
支持 mcpServers 配置的客户端示例(请将路径替换为实际克隆路径):
{
"mcpServers": {
"uart-mcp": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/uart-mcp", "run", "uart-mcp"],
"env": {
"UART_MCP_LOG_DIR": "/absolute/path/to/uart-mcp-data/logs"
}
}
}
}在 Windows 系统下,请使用绝对路径,例如 C:\\Users\\you\\src\\uart-mcp。UART_MCP_LOG_DIR 环境变量为可选配置;默认情况下日志将写入仓库目录下的 logs/ 文件夹。日志中可能包含设备输出、认证凭据等敏感信息,请妥善选择并保护该目录。
工具列表
工具 | 用途说明 |
| 列出当前主机可见的所有串口。 |
| 管理和查看后台捕获会话。 |
| 消费已捕获输出或等待指定的正则匹配/事件。 |
| 检索历史日志、按页浏览单日日志或清空内存缓冲区。 |
| 向已打开的捕获会话写入文本或 HEX 数据。 |
| 执行单次 HEX 发送或“发-收”交互操作。 |
| 无需打开串口,直接基于 YAML 协议定义解析 HEX 响应数据。 |
| 向类 Shell 串口控制台发送一组连续命令。 |
在使用捕获会话类工具前需先调用 serial_open,使用完毕后调用 serial_close。如果同时打开了多个会话,必须在操作中指定 port 参数。serial_read 工具会推进共享读取游标;如仅需查看而不消费游标,请使用 serial_get_recent。捕获工具接收的数据是以“行”为维度的,因此未以换行符结尾的提示符可能暂时不会出现在捕获队列中。
安全与限制说明
serial_write、serial_send、serial_query和serial_shell会直接向真实硬件发送数据。MCP 标注已将其标记为带有副作用(side-effecting),但此类标注仅供提示参考;使用前请务必确认目标端口与发送内容。serial_shell会原样发送传入的命令。它不是沙箱,不会对命令安全性进行校验。服务端专为本地 stdio 交互设计,未实现网络传输、身份鉴权或多用户访问控制。
捕获的日志为纯文本存储,除非操作人员手动清理,否则将长期保留。
串口权限、驱动安装、电平标准、波特率和流控要求均取决于主机系统和连接的硬件设备。
DTR/RTS 保持 pySerial 的默认设置。部分转接板或开发板在打开端口时可能会触发复位或进入 bootloader。
项目结构
uart_mcp_server.py: MCP stdio 服务端及捕获会话工具。uart_cli.py: CLI 工具以及被 MCP 工具复用的单次串口操作实现。uart_agent.py: 串口会话管理与底层设备 I/O 辅助模块。test_uart_mcp_server.py: 无硬件依赖的单元与回归测试。docs/: 硬件测试记录与实现备忘。
开源协议
MIT。详情参见 LICENSE。
Related MCP server: sbl-probe
English
A local Model Context Protocol server for UART and serial-port debugging. It exposes a newline-delimited stdio MCP endpoint and is intended to run on the same machine that has access to the serial adapter.
Features
Persistent capture sessions with a bounded in-memory ring buffer and daily log files.
Read newly captured lines, wait for regex/event matches, inspect recent output, and search historical logs.
Enumerate ports and perform one-shot HEX send/query operations.
Parse captured HEX data against YAML protocol descriptions.
Communicate with shell-like devices using a sequence of serial commands.
Cross-platform Python implementation using pySerial.
Requirements
Python 3.10 or newer.
A serial adapter and the appropriate OS-level device permissions for hardware use.
uv(recommended) orpip.
Install and run
Clone the repository, then install it in an isolated environment:
uv sync
uv run uart-mcpThe server uses MCP stdio. An MCP client launches it as a subprocess and exchanges JSON-RPC messages over stdin/stdout. Diagnostics are written to stderr so stdout remains reserved for the protocol.
Alternatively, install the project with pip and run the console command:
python -m pip install .
uart-mcpFor development and tests:
uv sync --group dev
uv run pytestThe automated tests use a fake serial device and do not require connected hardware.
MCP client configuration
Example configuration for clients that support mcpServers (adjust the path to your checkout):
{
"mcpServers": {
"uart-mcp": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/uart-mcp", "run", "uart-mcp"],
"env": {
"UART_MCP_LOG_DIR": "/absolute/path/to/uart-mcp-data/logs"
}
}
}
}On Windows, use absolute paths such as C:\\Users\\you\\src\\uart-mcp. The UART_MCP_LOG_DIR setting is optional; by default logs are written to the repository's logs/ directory. Logs may contain device output, credentials, or other sensitive data, so choose and protect the directory accordingly.
Tools
Tool | Purpose |
| Enumerate serial ports visible to the host. |
| Manage and inspect background capture sessions. |
| Consume captured output or wait for a regex/event. |
| Search persisted logs, page through a daily log, or clear the in-memory buffer. |
| Write text or HEX to an open capture session. |
| Perform one-shot HEX transmission or write/read transactions. |
| Parse a HEX response using a YAML protocol definition without opening a port. |
| Send a sequence of commands to a shell-like serial console. |
Use serial_open before the capture-session tools and serial_close when finished. If more than one session is open, specify port on operations that target a session. The serial_read tool advances a shared read cursor; use serial_get_recent for non-consuming inspection. Incoming data is line-oriented for capture tools, so prompts without a newline may not appear there.
Safety and limitations
serial_write,serial_send,serial_query, andserial_shelltransmit data to real hardware. MCP annotations mark these as side-effecting, but annotations are advisory; review the payload and target port before use.serial_shellsends the supplied commands as-is. It is not a sandbox and does not validate commands for safety.The server is designed for local stdio use. It does not implement network transport, authentication, or multi-user access control.
Capture logs are plain text and persist until removed by the operator.
Serial permissions, driver installation, electrical levels, baud rate, and flow-control requirements depend on the host and attached device.
DTR/RTS are left to pySerial defaults. Some adapters or boards may reset or enter a bootloader when a port is opened.
Project layout
uart_mcp_server.py: MCP stdio server and capture-session tools.uart_cli.py: CLI and one-shot serial operations reused by MCP tools.uart_agent.py: serial session and device I/O helpers.test_uart_mcp_server.py: hardware-free regression tests.docs/: hardware retest notes and implementation observations.
License
MIT. See LICENSE.
Available Tools
15 toolslist_portsARead-onlyIdempotent
List available serial ports on this machine.
Inputs: no named parameters.
protocol_parseARead-onlyIdempotent
Parse a raw HEX response against a YAML protocol action definition (offline).
Inputs: action (required), protocol (required), raw_hex, input_file.
serial_clear_bufferADestructive
Drop buffered lines and reset the read cursor; log files are kept.
Inputs: port.
serial_closeAIdempotent
Close a capture session, stop its reader thread, and release the port.
Inputs: port.
serial_get_logARead-onlyIdempotent
Page through one day's raw log file by line offset.
Inputs: date, port, limit, offset.
serial_get_recentARead-onlyIdempotent
Return the most recent N buffered lines regardless of read cursor.
Inputs: port, lines.
serial_openAIdempotent
Open a serial port with a background reader that continuously captures all incoming lines into a ring buffer and a daily log file. Call this first.
Inputs: port (required), parity, timeout, baudrate, +3 more.
serial_queryADestructive
One-shot write-then-read exchange; accepts hex or protocol+action from a YAML protocol file.
Inputs: port (required), hex, action, length, +7 more.
serial_readBRead-onlyIdempotent
Return lines captured since the previous serial_read (tail-follow semantics). Waits up to wait_ms for fresh data instead of returning empty.
Inputs: port, wait_ms, max_lines.
serial_searchARead-onlyIdempotent
Regex-search the full captured history (daily log files) — e.g. find every HardFault in the past hour.
Inputs: port, limit, events, pattern, +1 more.
serial_sendADestructive
One-shot raw HEX transmit (opens/closes the port; use serial_write when capturing).
Inputs: hex (required), port (required), parity, timeout, +3 more.
serial_shellCDestructive
One-shot command sequence over a shell-like device; collects a transcript.
Inputs: port (required), commands (required), parity, timeout, +7 more.
serial_statusARead-onlyIdempotent
Show every capture session: state, uptime, counters, unread lines, log file path. Omit 'port' to list all sessions.
Inputs: port.
serial_wait_forARead-onlyIdempotent
Block until a line matches a custom regex ('pattern') and/or built-in event presets ('events': error/hardfault/assert/panic/boot), then return once with the hit and preceding context. Ideal for watching boot logs without polling.
Inputs: port, events, pattern, timeout_ms, +1 more.
serial_writeBDestructive
Write text or HEX into an open capture session's port.
Inputs: hex, port, text, line_ending.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool has a clearly distinct role—port discovery, capture session management, read variants, write/send/query variants, and offline parsing—so agents can generally select the right tool. The main ambiguity is between serial_write and serial_send, and between serial_read and serial_get_recent, though their descriptions do clarify the intended use cases.
The vast majority of tools follow a serial_<verb> snake_case pattern, which is predictable and easy to scan. However, list_ports and protocol_parse break the serial_ prefix convention, and serial_status and serial_shell are noun-style rather than verb-style, creating minor inconsistencies.
Fifteen tools sits at the upper edge of the well-scoped range and mostly earns its place for a comprehensive UART toolkit. The one-shot variants (serial_send, serial_query, serial_shell) and protocol_parse add specialized capability but make the set feel slightly denser than a minimal capture-focused server.
The tool surface is very complete for UART debugging: it covers port enumeration, capture session lifecycle, continuous reading, writing, event waiting, history search, log paging, buffer reset, and protocol parsing. There are no obvious dead ends or missing core operations for the stated domain.
Related MCP Connectors
Live browser debugging for AI assistants — DOM, console, network via MCP.
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Remote MCP to publish, search, and get information. x402 v2 required.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceProvides serial debugging for embedded Linux targets, enabling boot log capture, automatic login, crash detection, U-Boot interrupt, and hardware reset via MCP protocol.-

sbl-probeofficial
AlicenseNot gradedqualityDmaintenanceSerial communication and protocol analysis MCP server that gives AI coding assistants direct access to serial ports for reading, writing, decoding, and capturing embedded device output.MIT- AlicenseNot gradedqualityDmaintenanceEnables humans and AI agents to collaboratively control serial ports via MCP tools or Web UI, with real-time data sharing across all participants.MIT
- FlicenseNot gradedqualityBmaintenanceEnables sharing two serial consoles between a local operator and MCP agents, allowing command execution and status monitoring on connected devices.-