Serial Hub 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., "@Serial Hub MCP Open COM3 at 115200 8N1 and show me the latest serial output."
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.
Serial Hub MCP
Windows 共享串口网关:一个常驻进程连接物理 COM,多个 OpenCode/MCP 会话和 Xshell Telnet 客户端可以同时输入、同时看输出。 不管理板子、不编译固件、不自动刷机。
v0.2 起默认自由并发读写。没有控制权、租约、接管按键、只读旁观模式,也不等待前一条命令完成后才允许下一次输入。 v0.1 的轮流控制设计已废弃。
v0.3 起完全取消认证。Xshell Telnet 连接即用,MCP/CLI 不读取、不创建令牌文件;两个入口仍只监听 127.0.0.1。默认信任本机环境。
OpenCode A ─ stdio MCP adapter ─┐
OpenCode B ─ stdio MCP adapter ─┼─ loopback HTTP ─ daemon ─ COM3 / COM8 / ...
Xshell 1 ─ loopback Telnet ─────┤
Xshell 2 ─ loopback Telnet ─────┘同一串口仍只有一个物理字节流、一个板端终端,不是多个独立 shell。多个客户端的按键/命令可以混在一起,Ctrl+C 会影响共同终端,输出向所有客户端广播。工具不擅自禁止并发,但不能保证各命令输出独立、提示符匹配属于当前调用,或多人同时输入时命令仍然有效。
安装(Windows / PowerShell)
需要 Python 3.11+、Git。无须管理员权限、虚拟串口驱动或板端网络服务。
git clone https://github.com/dongqifan/serial-hub_mcp.git
Set-Location serial-hub_mcp
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1手动安装与测试:
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e '.[test]'
.\.venv\Scripts\python.exe -m pytest -q服务、MCP 适配器必须使用相同的 SERIAL_HUB_API_PORT。SERIAL_HUB_HOME 只决定服务的日志/诊断目录,不再用来共享认证信息。
Related MCP server: coserial
启动共享服务
断开其他软件对真实 COM 的直接连接;Xshell 改接本工具提供的 Telnet。
# 按需打开:MCP open_port 时开始接收日志
.\.venv\Scripts\serial-hub.exe serve
# 或启动时打开指定串口,可重复 --port
.\.venv\Scripts\serial-hub.exe serve --port COM3 --baudrate 115200
# 另一个终端查看状态和 Telnet 入口
.\.venv\Scripts\serial-hub.exe status默认 115200 / 8N1 / 无流控,DTR/RTS 预设低电平;其他参数通过 MCP open_port 传入。驱动/硬件仍可能在打开时产生控制线毛刺,不能保证不复位。 参数不同的重复打开会拒绝,不会悄悄改现有连接。
命令行管理 COM 占用 / 释放
OpenCode / 命令(全局)
已配置 serial_hub MCP 后,执行一次:
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-opencode-commands.ps1在任意项目的 OpenCode 中使用:
/serial-ports
/serial-open COM3 115200
/serial-status COM3
/serial-release COM3/serial-status 无参数时列出全部状态。/serial-open 省略波特率时默认 115200/8N1/无流控/DTR 和 RTS 低,不发送测试文本。/serial-release 只释放指定 COM,保留服务端拒绝正在使用端口的规则。
这些是交给当前会话 AI 执行的命令模板,通过 MCP 查询/操作,不是绕过工具权限的直接 shell 快捷键;请以实际工具返回为准。服务或 MCP 不可用时不自动启动服务。文件安装在 ~/.config/opencode/commands/(设置 XDG_CONFIG_HOME 时遵循该目录),自动加载,必要时 /reload,不需要重启 OpenCode。安装脚本不会覆盖内容不同的现有同名命令。
PowerShell 命令
先启动共享服务,然后在项目目录的 PowerShell 使用:
# 列出系统串口及本服务占用状态(表格)
.\.venv\Scripts\serial-hub.exe ports
# 打开并由共享服务持有 COM3;同配置重复打开会复用,不发送串口文本
.\.venv\Scripts\serial-hub.exe open COM3 --baudrate 115200
# occupy 与 open 同义
.\.venv\Scripts\serial-hub.exe occupy COM3 --baudrate 115200
# 查看指定 COM 的串口参数、连接状态、Telnet 入口、客户端数量、活跃 execute 和日志路径
.\.venv\Scripts\serial-hub.exe status COM3
# 释放 COM3,其他软件随后可以直接打开物理串口;共享服务继续运行
.\.venv\Scripts\serial-hub.exe release COM3
# close 与 release 同义
.\.venv\Scripts\serial-hub.exe close COM3
# 全部状态 / 适合脚本读取的 JSON
.\.venv\Scripts\serial-hub.exe status
.\.venv\Scripts\serial-hub.exe ports --json也可以将 .\.venv\Scripts\serial-hub.exe 替换为 .\.venv\Scripts\python.exe -m serial_hub_mcp.cli。
open支持--baudrate、--bytesize、--parity N/E/O/M/S、--stopbits、--flow-control none/rtscts/xonxoff、--dtr、--rts;默认 115200/8N1/无流控/DTR 和 RTS 低。打开串口仍可能造成硬件控制线变化。ports的open表示本服务持有;disconnected表示服务仍保留断线对象,需要 close/open 恢复;not-open只表示本服务未持有,不证明该 COM 没有被其他软件占用。不提供其他进程占用者查询。release/close遇到 Telnet 客户端或活跃execute会拒绝,先断开对应 Telnet 并结束调用。不提供强制中断;被动 MCP 读取者不计入连接数,释放前仍需确认其他会话不再需要日志。释放后对应 Telnet 入口关闭,其他 COM 不受影响;下次
open才恢复。MCP 仍可再次打开该端口,本命令不是禁止访问开关。命令只管理正在运行的 daemon,不自动启动服务或自动保存开机串口配置。失败输出错误并返回非零退出码。
只启动一个 daemon(默认 API 端口 8766)。关闭 MCP 会话不关闭 daemon,服务退出才关闭物理串口。首次打开前的日志无法补抓。
OpenCode 全局接入(V2)
将下列内容合并到 ~/.config/opencode/opencode.jsonc,替换安装路径并保留已有设置:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"serial_hub": {
"type": "local",
"command": ["D:/tools/serial-hub_mcp/.venv/Scripts/python.exe", "-m", "serial_hub_mcp.mcp_server"],
"cwd": "D:/tools/serial-hub_mcp"
}
}
}
}每个适配器只连接 daemon,不占用 COM。配置自动加载;必要时 /reload,通过 /mcps 检查。
OpenCode 的 _meta["ai.opencode/sessionID"] 只标注 TX 来源,不用于认证、获取控制权或限制其他输入。其他 MCP 客户端使用每个适配器进程一个来源标识。本机连接无需任何凭据。
使用 COM3,115200 8N1 无流控,先读取输出。
向 COM3 直接发送 pwd 和回车。
在 COM3 执行命令并等待指定文本;其他会话和 Xshell 仍可同时输入。工具 | 用途 |
| 实时枚举串口与打开的共享连接 |
| 打开/复用 COMx,开始持续 RX,返回 Telnet 入口 |
| 共享模式、活跃 execute 数量、写入序号、游标和连接状态 |
| 独立游标读取 RX,不消费别人的输出;含原始 base64 |
| 立即发送文本/原始字节,不自动换行,无须申请控制权 |
| 立即发送文本及换行,再独立观察共享 RX 直到字面量匹配或超时 |
| 显式关闭;有 Telnet 连接或活跃 execute 时拒绝关闭 |
execute 的共享输出语义
不获取控制权、不排队等其他命令结束。其他客户端可以在它等待输出时随时写入。
每个调用有独立 RX 游标,但看到的是共同输出,可能包含其他调用者的响应。
expect是字面量,不是正则/退出码;任何人的输出都可能触发匹配。matched 不证明你的命令已完成或执行成功。返回
shared_output=true、additional_writes_observed(发送后、返回前观察到的其他写入次数)和警告。该计数不是输出归属证明,先前命令也可能还在输出。超时不发送 Ctrl+C、不自动重试、不禁止后续输入。调用者自行判断终端状态;没有 acknowledge_state 步骤。
单次结果最多保留 64 KiB 尾部;完整 RX 记录在有界本机轮转日志。
wait_seconds仅为兼容 v0.1 保留,已忽略。
read_output 无游标时回放保留缓冲,使用返回的 cursor 可增量读取。每个人自行保存游标,互不消费。文本编码边界可能切开,严格还原请使用 base64 和增量解码。关闭重开后旧游标失效。RX 内存每端口 1 MiB,单次最多 64 KiB,bytes_lost 报告缓冲覆盖。
Xshell:连接后即可输入
MCP 打开串口,或 daemon 启动时指定
--port COM3。Xshell 新建 TELNET 会话,主机
127.0.0.1。端口以open_port/status返回值为准。默认尝试
2300 + COM号:COM3 → 2303、COM8 → 2308;占用时分配其他端口。字符编码与 daemon
--encoding一致,默认 UTF-8。关闭本地回显,使用普通远程终端输入。连接后直接收发,无用户名、密码或 Access token 提示。 无需 Ctrl+] 接管,没有管理按键,Ctrl+] 也会直接转发给串口(客户端自己截获的快捷键除外)。板端操作系统自己的登录提示不在本工具控制范围内。
多个 Xshell 标签页、多个 AI 会话都可以直接写入。Telnet CR LF / CR NUL 转成一次串口回车,控制字符直接转发。粘贴与人工逐字输入的分块可能不同,多方输入可能相互穿插;不进行行缓冲或命令级调度。
关闭某个 Xshell 标签只断开那个连接,不关闭真实串口。
并发、故障与安全边界
每个收到的写入块通过一次有界同步串口 write 发送,块内不被其他 API 调用插字节。只串行化物理写入这一瞬间,不锁住命令/响应周期;硬件本来只能按顺序传输字节。
驱动写入超时 1 秒,可能使事件循环暂时阻塞;高负载需实际压力验证。
串口断线后不自动重连,也不重放命令;确认使用者结束后显式 close/open,不把 COM3 自动迁移到 COM8。
被动 MCP 读者不是持久订阅,关闭前需确认无人需要后续日志;端口关闭拒绝正在连接的 Telnet 和活跃 execute。
不自动发送回车、Ctrl+C、BREAK,也不自动复位、重试命令。用户通过 send/Xshell 发出的控制键照常转发,可能影响其他人的程序。
API 和 Telnet 仅监听 IPv4 loopback,均无认证,默认信任所有能访问这些本机端口的进程/用户;HTTP 仍校验 Host/Origin。这不是多用户隔离系统,Host/Origin 校验也不是身份认证。
Telnet 为明文协议,不要向公网/局域网转发;远程团队共享需另行设计身份认证和加密。
原始日志可含密码、客户数据。Base64 不是加密。默认每端口 8 MiB × 5 份,最多 32 个打开端口;日志有覆盖,重要资料自行安全归档。
工具不判断串口命令的危险程度,安装工具不等于授权 AI 刷机、重启、擦除或改配置。
文件位置和自动启动
默认 %LOCALAPPDATA%\serial-hub-mcp\:
logs/COM3.jsonl 原始 RX/TX 与事件,不上传
logs/COM3.jsonl.1 轮转日志
daemon.stderr.log 启动诊断(pythonw)SERIAL_HUB_HOME:daemon 的日志/诊断目录,MCP 不依赖此目录。SERIAL_HUB_API_PORT:API 端口,默认 8766,两者必须一致。
验证手动启动后,可注册当前用户登录启动任务(不需要管理员权限):
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\register-startup.ps1
# 先停止手动 daemon,再启动任务,勿同时运行两个
Start-ScheduledTask -TaskName SerialHubMCP任务默认不打开串口,由 MCP 按需打开。它是登录启动,不是无人登录时的系统服务。移除任务:
Unregister-ScheduledTask -TaskName SerialHubMCP -Confirm:$false更新:停止 daemon,git pull,重新运行安装脚本,启动 daemon,再 /reload MCP 让工具说明更新。服务重启会暂时断开 Telnet,需重新连接;不会自动恢复打开的端口。v0.1 已运行适配器的三个旧控制 API 在 v0.2 服务端只返回兼容提示,不再限制输入;新适配器不暴露这些工具。
升级 v0.3 后,旧的 access.token 文件不再读取或校验,可保留,也可自行删除;程序不会自动删除旧文件。token-path 命令已移除。请重新加载旧 MCP 适配器以停止它读取旧令牌。
测试
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m compileall -q src默认测试全部使用模拟串口,不访问实际 COM。覆盖:多个 execute 在任何响应之前都已发出、等待期间其他 MCP/Telnet 仍可写入、独立读取、超时不阻止输入、控制键透传、无令牌的 MCP/CLI/API/Telnet 连接、Host/Origin 边界、断线及日志。真实硬件范围记录在 docs/VALIDATION.md,模拟 Telnet 测试不等于真实 Xshell UI 验证。
MIT;第三方依赖保留各自许可证。
Available Tools
8 toolsclose_portB
Explicitly close idle unused port. Refuses Telnet clients or active execute calls.
Passive MCP readers are not tracked as subscriptions: confirm nobody still needs capture first.
Inputs: port (required).
executeA
Send immediately and independently observe SHARED RX until literal expect or timeout.
Other MCP/Telnet clients may write at any time; no command/response queue or isolation. Any client's output can satisfy expect, so a match is not proof your command completed. additional_writes_observed counts subsequent writes from any source during this call. Result is bounded to 64 KiB. No automatic Ctrl+C, retry or input gating after timeout. wait_seconds is deprecated and ignored (v0.1 compatibility); no input lease exists.
Inputs: port (required), text (required), expect (required), newline, +3 more.
list_portsA
Enumerate Windows COM ports and shared open connections; does not open hardware.
Inputs: no named parameters.
open_portA
Open/reuse COMx, start RX capture, return Xshell Telnet endpoint. Never sends text.
Confirm serial parameters with user; driver/hardware may glitch DTR/RTS on open. Existing different settings are rejected, not silently replaced.
Inputs: port (required), dtr, rts, parity, +4 more.
port_statusC
Inspect shared input mode, active executions, terminal clients, RX cursors and disconnect state.
Inputs: port (required).
read_outputA
Read RX without consuming other sessions' data. Reuse returned cursor for increments.
No cursor replays retained buffer. base64 is lossless; text can split UTF-8 chunks. Old cursors are rejected after close/reopen. bytes_lost reports ring overflow.
Inputs: port (required), cursor, encoding, max_bytes, +1 more.
sendB
Immediately send exact text/control characters (no implicit newline). No lease or takeover required.
Inputs: port (required), text (required), encoding.
send_bytesA
Immediately send exact base64-encoded bytes. No lease; never resets, flushes or retries automatically.
Inputs: port (required), base64_data (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool maps to a distinct lifecycle stage (list, open, status, read, close) plus a small write family. The send / send_bytes / execute trio is the only fuzzy area, but the descriptions clearly separate text vs base64 vs send-and-observe semantics, so misselection risk is low.
Predominantly verb_noun snake_case (list_ports, open_port, read_output, close_port) with two bare verbs (send, execute) and one noun-first name (port_status). Readable and predictable overall, with only minor deviations in style.
Eight tools is well-scoped for a serial-port bridge: one tool per operation, no redundant wrappers or bloat. Nothing appears vestigial, and no obvious operation is missing a slot.
Full session lifecycle is covered: discovery, open with parameters, state inspection, reads with cursors, multiple write modes, and closing. Gaps are minor but real: no way to reconfigure baud/parity in place (must close and reopen), and no flush/break or DTR/RTS control despite the documented glitch risk.
Maintenance
Related MCP Connectors
2,000+ MCP servers read at source level. Know what one does before you connect. Free, no key.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Send files and text with a six-digit transfer code. Remote MCP for agents.
Related MCP Servers
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 gradedqualityCmaintenanceLocal MCP server that lets AI agents read and control attached Xshell terminal sessions.10-
- FlicenseNot gradedqualityBmaintenanceEnables sharing two serial consoles between a local operator and MCP agents, allowing command execution and status monitoring on connected devices.-