coserial

简体中文 | English

Collaborative Serial Debug Bridge. Humans and AI Agents co-control serial ports via MCP tools or Web UI, sharing all IO data in real time. Humans, Agents, and hardware — all on the same page.

Architecture

Agent A ── MCP stdio ── coserial-client ──┐
Agent B ── MCP stdio ── coserial-client ──┤
Agent C ── MCP stdio ── coserial-client ──┤
...                                       │ HTTP (localhost)
Human A ── Web UI ────────────────────────┤
Human B ── Web UI ────────────────────────┤
...                                       ▼
                         coserial-server
                         ├── HTTP API (/mcp/…)     ← MCP tool calls
                         ├── WebSocket /ws         ← Web UI real-time data
                         ├── GET /                 ← Web UI (HTML/CSS/JS)
                         ├── SessionManager
                         │   ├── COM1
                         │   ├── COM2
                         │   └── ...
                         └── Web UI Monitor

Features

🤝 Human-Agent Collaboration — Humans and AI Agents share the same serial session, debugging in real time
🔌 MCP Tool Control — Agents read/write serial ports, wait for pattern matches, send commands, etc. via standard MCP protocol
🖥️ Web UI Monitor — Dark theme, real-time RX/TX data stream, HEX display, search highlighting, log export
🔄 Three-Party Data Sync — Agent I/O and Web UI I/O write to the same buffer — nobody misses anything
📡 Multi-Session Management — Connect to multiple serial ports simultaneously, switch via Web UI dropdown
🔧 Signal Line Control — DTR/RTS hardware reset support
📝 Log Persistence — Serial I/O automatically recorded to file
🎯 Zero-Build Frontend — Vanilla HTML/CSS/JS, no frontend toolchain required

Quick Start

Install

# Clone the repo
git clone https://github.com/FlipFlopszzz/coserial.git
cd coserial

# Install dependencies (requires uv)
uv sync

Or with pip:

pip install -e .

Register with Claude Code

After installation, register coserial as an MCP server so Claude Code can use it:

# Global (recommended) — available in all projects
uv run coserial init --global

# Project-level — creates .mcp.json + .claude/launch.json in target directory
uv run coserial init /path/to/your-project

init --global writes to ~/.claude.json via claude mcp add --scope user.

init (project-level) writes to .mcp.json + .claude/launch.json in the target directory, enabling both MCP tools and Claude Desktop Preview.

Launch

# Start server + open Web UI (manual debug mode)
uv run coserial

# Start and auto-connect to COM20
uv run coserial COM20

# List all active sessions
uv run coserial list

# Start server only (headless)
uv run coserial-server

Use in Claude Code

Once registered, call MCP tools directly in any Claude Code session:

server()                          → Start/discover server process
open_session(port="COM20")        → Open serial port
preview(port=37210)               → Get Preview URL
preview_start("coserial-web-ui")  → Open Web UI in Claude Desktop
command(session_id, "AT+GMR", expect="OK", newline=True)  → Send & wait

MCP Tools

Tool	Description
`server()`	Discover/start server process, returns port
`open_session(port, baud)`	Create a serial session, returns session_id
`close_session(session_id)`	Close a specific session
`write(session_id, data)`	Send data to serial port
`read(session_id, timeout, size)`	Read buffer data
`wait_for(session_id, pattern, timeout)`	Wait for output matching a regex
`command(session_id, data, expect, timeout)`	Send command and wait for response
`set_params(session_id, baud, ...)`	Dynamically adjust serial parameters
`get_params(session_id)`	Get full session parameters
`set_signals(session_id, dtr, rts)`	Control DTR/RTS signal lines
`list_ports()`	List available serial ports
`list_sessions()`	List all active sessions
`web(port)`	Open Web UI in system browser
`preview(port)`	Return URL for Agent's embedded browser
`shutdown_server()`	Shut down server process

Web UI

Open http://127.0.0.1:37210/ directly in your system browser, or via any Agent tool's embedded browser.

Project Structure

coserial/
├── pyproject.toml
├── src/coserial/
│   ├── __main__.py       # Entry: uv run coserial
│   ├── client.py         # MCP stdio client → HTTP proxy to server
│   ├── server.py         # Server: HTTP API + WebSocket + Web UI
│   ├── session.py        # SessionBuffer + SerialSession + SessionManager
│   └── web_ui/
│       └── index.html    # Single-page HTML, inline CSS/JS

Dependencies

Python >= 3.11
pyserial — Serial communication
mcp — MCP SDK (FastMCP)
websockets — WebSocket server
aiohttp — HTTP server
pywin32 — Windows process management
Icons from IconPark

License

MIT License

coserial

coserial

Architecture

Features

Quick Start

Install

Register with Claude Code

Launch

Use in Claude Code

MCP Tools

Web UI

Project Structure

Dependencies

License

Latest Blog Posts

MCP directory API