Skip to main content
Glama

uart-mcp

中文 | English


中文

用于 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/ 文件夹。日志中可能包含设备输出、认证凭据等敏感信息,请妥善选择并保护该目录。

工具列表

工具

用途说明

list_ports

列出当前主机可见的所有串口。

serial_open, serial_close, serial_status

管理和查看后台捕获会话。

serial_read, serial_get_recent, serial_wait_for

消费已捕获输出或等待指定的正则匹配/事件。

serial_search, serial_get_log, serial_clear_buffer

检索历史日志、按页浏览单日日志或清空内存缓冲区。

serial_write

向已打开的捕获会话写入文本或 HEX 数据。

serial_send, serial_query

执行单次 HEX 发送或“发-收”交互操作。

protocol_parse

无需打开串口,直接基于 YAML 协议定义解析 HEX 响应数据。

serial_shell

向类 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) or pip.

Install and run

Clone the repository, then install it in an isolated environment:

uv sync
uv run uart-mcp

The 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-mcp

For development and tests:

uv sync --group dev
uv run pytest

The 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

list_ports

Enumerate serial ports visible to the host.

serial_open, serial_close, serial_status

Manage and inspect background capture sessions.

serial_read, serial_get_recent, serial_wait_for

Consume captured output or wait for a regex/event.

serial_search, serial_get_log, serial_clear_buffer

Search persisted logs, page through a daily log, or clear the in-memory buffer.

serial_write

Write text or HEX to an open capture session.

serial_send, serial_query

Perform one-shot HEX transmission or write/read transactions.

protocol_parse

Parse a HEX response using a YAML protocol definition without opening a port.

serial_shell

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, and serial_shell transmit data to real hardware. MCP annotations mark these as side-effecting, but annotations are advisory; review the payload and target port before use.

  • serial_shell sends 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 tools
list_portsA
Read-onlyIdempotent

List available serial ports on this machine.

Inputs: no named parameters.

protocol_parseA
Read-onlyIdempotent

Parse a raw HEX response against a YAML protocol action definition (offline).

Inputs: action (required), protocol (required), raw_hex, input_file.

serial_clear_bufferA
Destructive

Drop buffered lines and reset the read cursor; log files are kept.

Inputs: port.

serial_closeA
Idempotent

Close a capture session, stop its reader thread, and release the port.

Inputs: port.

serial_get_logA
Read-onlyIdempotent

Page through one day's raw log file by line offset.

Inputs: date, port, limit, offset.

serial_get_recentA
Read-onlyIdempotent

Return the most recent N buffered lines regardless of read cursor.

Inputs: port, lines.

serial_openA
Idempotent

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_queryA
Destructive

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_readB
Read-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_sendA
Destructive

One-shot raw HEX transmit (opens/closes the port; use serial_write when capturing).

Inputs: hex (required), port (required), parity, timeout, +3 more.

serial_shellC
Destructive

One-shot command sequence over a shell-like device; collects a transcript.

Inputs: port (required), commands (required), parity, timeout, +7 more.

serial_statusA
Read-onlyIdempotent

Show every capture session: state, uptime, counters, unread lines, log file path. Omit 'port' to list all sessions.

Inputs: port.

serial_wait_forA
Read-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_writeB
Destructive

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

    A3.7/5.0

    Scored across 15 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Provides serial debugging for embedded Linux targets, enabling boot log capture, automatic login, crash detection, U-Boot interrupt, and hardware reset via MCP protocol.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Serial 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables humans and AI agents to collaboratively control serial ports via MCP tools or Web UI, with real-time data sharing across all participants.
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables sharing two serial consoles between a local operator and MCP agents, allowing command execution and status monitoring on connected devices.
      -