Submit
tt33415366

Serial Bridge

Community tt33415366
Updated

Serial Bridge is a Hub that shares two serial consoles between a local Operator and MCP Agents.

Serial Bridge

Serial Bridge is a Hub that shares two serial consoles between a local Operatorand MCP Agents. It is not OS-specific: install the Python packages inrequirements.txt and run it on any host with Python 3.10+. The Hub lives inthe serial_bridge/ package; start it with python -m serial_bridge or theroot app.py shim.

Install and start

Python 3.10 or newer is recommended.

python -m pip install -r requirements.txt
python -m serial_bridge

Shell snippets below use PowerShell ($env:NAME = "..."). On bash or zsh, set thesame names with export NAME=....

The Hub opens your browser to the console at http://127.0.0.1:8765/ once itis listening. The root app.py shim is equivalent. To start without opening abrowser tab:

$env:SERIAL_BRIDGE_OPEN_UI = "off"
python -m serial_bridge

Or pass --no-open-ui. Use --open-ui to force open when the environmentdisables it. Unset SERIAL_BRIDGE_OPEN_UI means open by default; only0, false, no, and off (case-insensitive) disable it.

On first boot the Hub auto-generates an Access Token into serial_bridge.tokenbeside the Port Binding config file (override the path withSERIAL_BRIDGE_TOKEN_FILE). Do not commit the secrets file.

Open Setup (http://127.0.0.1:8765/setup) on the Hub host to copy the HubURL, view the Access Token, rotate it, and paste a Cursor mcpServers snippet.Setup secrets (token plaintext, Rotate, and the secret-bearing snippet) arevisible only on loopback (127.0.0.1 / ::1).

Alternatively, set SERIAL_BRIDGE_TOKEN before starting the Hub and give thesame secret to the MCP client. The env var overrides the secrets file for thatprocess lifetime; Rotate still rewrites the file but warns until env is unset orthe Hub is restarted without it.

MCP authentication is required even from loopback. Do not put the token in sourcecontrol, static frontend files, URLs, or logs.

The Hub listens on 0.0.0.0:8765, so it is reachable from the local network.Use an appropriate host firewall and a strong token. Remote Agents cannotchange modes or Port Bindings.

MCP

Use Setup (/setup) on the Hub host for a copy-paste Cursor config. Manualwiring:

Configure the Agent's Streamable HTTP MCP connection with:

URL: http://<hub-host>:8765/mcp
Authorization: Bearer <SERIAL_BRIDGE_TOKEN>

Use /mcp exactly; the Web UI is at /. The MCP Server exposes:

  • serial_status: read the current mode and each Target's Port Binding,open state, and busy hint.
  • serial_exec: send one text command and capture output until an idle gap,an optional prompt match, or the 60-second timeout.
  • serial_send: send a text line or Raw Payload without waiting for output.

To exercise status and Exec:

  1. Open the Web UI locally and switch to Bridge Mode.
  2. Connect the MCP client to the URL above with the Bearer header.
  3. Call serial_status with no arguments and confirm mode is bridge andthe intended Target is open.
  4. Call serial_exec with {"target":"linux","cmd":"uname -a"} or{"target":"rtos","cmd":"help"}.
  5. If the device has a stable prompt, optionally pass prompt; setprompt_is_regex to true only when the prompt value is a regularexpression.

Exec accepts the Target names linux and rtos, not serial device names. Itreturns captured output plus timed_out, truncated, and aborted flags.

Exec output and the live/*.log transcripts are plain text with ANSI escapesremoved. The Web UI instead interprets the escapes and shows device colors.

Port Binding

A Port Binding assigns a Target to a serial device path and baud rate.Built-in defaults are Windows-style (linux on COM3, rtos on COM6, both115200); on Linux or macOS set paths such as /dev/ttyUSB0 instead.

Override defaults before startup with environment variables:

$env:SERIAL_BRIDGE_LINUX_PORT = "COM8"
$env:SERIAL_BRIDGE_LINUX_BAUD = "57600"
$env:SERIAL_BRIDGE_RTOS_PORT = "COM9"
$env:SERIAL_BRIDGE_RTOS_BAUD = "115200"
python -m serial_bridge

Equivalent CLI flags are --linux-port, --linux-baud, --rtos-port, and--rtos-baud. SERIAL_BRIDGE_CONFIG or --config selects the persisted JSONfile. The load order is built-in defaults, then environment/CLI values, thenthe persisted file; saved Web UI values win.

Only the Operator can edit Port Bindings, and only in CRT Mode while theHub has released the ports. The Web UI lists the detected serial ports in adropdown per Target; use Scan to re-enumerate after plugging in an adapter.Changes made in the Web UI persist for restart.

Live Directory

The Live Directory is where the Hub writes per-Target Bridge session logs andbridge_status.json. The default is <app-dir>/live/ beside the project root(same directory as serial_bridge.json and the root app.py shim).

Override before startup with:

$env:SERIAL_BRIDGE_LIVE_DIR = "D:\logs\serial-bridge"
python -m serial_bridge

Or pass --live-dir. Load order matches Port Binding: built-in default, thenenvironment/CLI, then the persisted config file; Web UI saves win.

Each time the Operator enters Bridge Mode, the Hub creates fresh log filesnamed <TargetName>-YYYY-MM-DD-HHMMSS.log (local time, 24-hour clock). A secondBridge session creates new files; older logs are left in place and are notmigrated when you change the Live Directory or rename a Target.

Edit the Live Directory in the Web UI Bindings panel in CRT Mode only (sameloopback-only write path as Port Binding). The footer shows the configureddirectory and current session log filenames when assigned.

Bridge Mode and CRT Mode

  • Bridge Mode: the Hub owns the configured serial ports. The Operator andAgents can send commands and observe the same live transcripts.
  • CRT Mode: the Hub releases the ports for SecureCRT or another exclusiveserial client. MCP Exec and Send fail until the Operator returns to BridgeMode.

Disconnect SecureCRT before entering Bridge Mode. Switching to CRT Mode abortsan in-flight Exec and may return partial output.

Raw Send warning

serial_send with raw_hex writes arbitrary bytes without text-line framingor an automatic line ending. This is full console power: control bytes caninterrupt boot, terminate processes, alter device state, or make a sessionunresponsive. Prefer serial_exec for commands, and use Raw Payloads onlywhen the exact byte sequence and device impact are understood.

MCP Server · Populars

MCP Server · New