Serial Web Terminal MCP

A Model Context Protocol server that gives AI coding assistants (Claude Code, Cursor, Windsurf, etc.) the ability to interact with serial port devices.

AI agents can connect to serial devices, send commands, and capture output — while users watch the entire process in real-time through a browser-based terminal.

✨ Features

• 🔌 Serial Connection — Connect to COM ports, /dev/ttyUSB*, /dev/ttyS*, etc. with automatic login
• 🖥️ Web Terminal — xterm.js browser terminal showing real-time serial I/O (like Xshell)
• 🤖 MCP Server — Native tool integration; AI agents call directly via MCP protocol
• 📝 Timestamped Logs — Every line logged with timestamps, daily rotation, matches terminal display exactly
• ⌨️ Bidirectional — AI sends commands + user can type manually in the browser terminal
• 🌐 Multi-language Login — Auto-detects login/password prompts in English, Chinese, and Japanese
• ⏱️ Wait-and-Send — Wait for specific output then immediately send data (e.g., uboot password windows)
• 🛡️ Timeout Recovery — Automatic Ctrl+C on timeout, no hung sessions

📦 Installation

pip install mcp pyserial aiohttp

Or from requirements:

pip install -r requirements.txt

🚀 Quick Start

1. Configure your AI client

Claude Code (.mcp.json in project root or ~/.claude/claude_config.json):

{
  "mcpServers": {
    "serial-terminal": {
      "command": "python",
      "args": ["/path/to/serial_mcp_server.py"]
    }
  }
}

Cursor (Settings → MCP → Add Server):

{
  "mcpServers": {
    "serial-terminal": {
      "command": "python",
      "args": ["/path/to/serial_mcp_server.py"]
    }
  }
}

See examples/ for ready-to-use configuration files.

2. Talk to your AI assistant

> List available serial ports
AI: [calls serial_list_ports] → Found COM3, COM4...

> Connect to COM3, username admin, password ****
AI: [calls serial_connect(port="COM3", login_user="admin", login_pass="****")]
    → Serial connected, Web terminal: http://localhost:8080

> Run uname -a
AI: [calls serial_send(command="uname -a")]
    → Linux device 4.19.246 aarch64 GNU/Linux

Open http://localhost:8080 in your browser to watch AI's serial operations in real-time.

🔧 MCP Tools

Tool	Description
serial_list_ports	List all available serial port devices
serial_connect	Connect to a serial port and start the web terminal (supports auto-login)
serial_send	Send a shell command and return device output
serial_raw	Send raw data (e.g., Ctrl+C = \x03)
serial_wait_send	Wait for specific output, then immediately send data (for time-critical operations)
serial_status	Check current connection status
serial_log	Get timestamped operation logs
serial_disconnect	Disconnect and stop the web terminal

serial_connect

Connect to a serial device with optional auto-login.

Parameter	Type	Default	Description
port	str	(required)	Serial device name (e.g., COM3, /dev/ttyUSB0)
baudrate	int	115200	Baud rate
login_user	str	""	Auto-login username (skip if empty)
login_pass	str	""	Auto-login password
init_cmd	str	unset TMOUT	Command to run after login (prevent session timeout)
web_port	int	8080	Web terminal port

serial_send

Send a shell command and capture output.

Parameter	Type	Default	Description
command	str	(required)	Shell command to execute
timeout	int	8	Response timeout in seconds

serial_wait_send

Wait for a specific string in serial output, then immediately send data. Ideal for:

• Entering uboot during reboot (3-second password window)
• Responding to login prompts
• Any "wait for X, then send Y" automation

Parameter	Type	Default	Description
wait_for	str	(required)	Target string to wait for
send_data	str	(required)	Data to send when target is found
timeout	int	60	Max wait time in seconds
trigger	str	""	Optional data to send before waiting (e.g., \r\n to re-trigger a static prompt)

🖥️ Standalone Usage (without MCP)

serial_web.py can run independently via HTTP API:

# Start with auto-login
python serial_web.py --port COM3 --baud 115200 \
  --login-user admin --login-pass secret \
  --init-cmd "unset TMOUT"

# List available ports
python serial_web.py --list

HTTP API

# Send a command
curl -s -X POST http://localhost:8080/api/send \
     -H "Content-Type: application/json" \
     -d '{"command":"ls /","timeout":5}'

# Send raw data (Ctrl+C)
curl -s -X POST http://localhost:8080/api/raw \
     -H "Content-Type: application/json" \
     -d '{"data":"\x03"}'

# Wait-and-send
curl -s -X POST http://localhost:8080/api/wait-send \
     -H "Content-Type: application/json" \
     -d '{"wait_for":"login:","send_data":"admin","timeout":30}'

# Check status
curl -s http://localhost:8080/api/status

# Get logs
curl -s "http://localhost:8080/api/log?lines=50"

CLI Arguments

Argument	Default	Description
--port	(required)	Serial device name (COM3, /dev/ttyUSB0)
--baud	115200	Baud rate
--web-port	8080	Web server port
--login-user	(none)	Auto-login username
--login-pass	(none)	Auto-login password
--init-cmd	unset TMOUT	Post-login command (use ; for multiple)
--prompt-regex	(auto)	Custom prompt detection regex
--list	—	List available serial ports

📝 Log Format

Logs are saved to logs/serial_YYYYMMDD.log (daily rotation):

2026-08-06 15:32:22  device # uname -a
2026-08-06 15:32:22  Linux device 4.19.246 aarch64 GNU/Linux
2026-08-06 15:32:23  device # cat /proc/cpuinfo | head -5
2026-08-06 15:32:23  processor	: 0
2026-08-06 15:32:23  >>> 自动登录流程完成

• Terminal output: timestamp content (extracted from xterm.js buffer — matches browser display exactly)
• System events: timestamp >>> message (login, startup, etc.)

Log line fidelity:

• No wrap splitting — lines soft-wrapped by the terminal (80-column wrap) are merged back into a single logical line
• Progress-bar aware — \r overwrite sequences (10%\r20%\r30%) are collapsed to the final visible state (30%)
• Backspace-aware — manual edits with backspace are recorded as the final edited line
• Every line always carries a timestamp prefix

🏗️ Architecture

AI Agent (Claude Code / Cursor / ...)
  └─ MCP Protocol (stdio)
      └─ serial_mcp_server.py
          └─ HTTP API
              └─ serial_web.py (aiohttp)
                  ├─ Serial Port (pyserial)
                  ├─ Web Terminal (xterm.js + WebSocket)
                  └─ Log Recording

Browser
  └─ http://localhost:8080
      ├─ xterm.js terminal (real-time serial data)
      └─ Log panel (timestamped logs)

📁 Project Structure

serial-web-terminal/
├── serial_web.py              # Core: Web terminal + HTTP API
├── serial_mcp_server.py       # MCP Server (wraps HTTP API)
├── tests/
│   └── test_regression.py     # Regression test suite (68 tests)
├── examples/
│   ├── claude-code.json       # Claude Code MCP config
│   └── cursor.json            # Cursor MCP config
├── requirements.txt
├── LICENSE
└── README.md

🧪 Testing

Run the regression test suite (no physical serial device required):

python tests/test_regression.py -v

Tests cover:

• Output cleaning (ANSI stripping, echo removal, prompt removal)
• Prompt detection (shell prompts, known prompts)
• Log line buffering (backspace handling, partial lines, ANSI cleaning)
• Auto-login keyword detection (English, Chinese, Japanese)
• Command send/receive (mock serial, timeout, Ctrl+C recovery)
• Wait-and-send (immediate match, dynamic match, timeout, trigger)
• HTML page structure (no duplicate IDs, required elements)
• MCP server tool registration
• HTTP API endpoints (status, send, raw, log — error handling)
• Security (no hardcoded credentials, .gitignore coverage)

🌐 Auto-Login

The auto-login flow supports multi-language prompts:

Language	Login Prompts	Password Prompts
English	login:	Password:
Chinese	登录: 用户名:	口令: 密码:
Japanese	—	パスワード:

Login flow:

1. Send Enter to wake the terminal
2. Detect login: prompt → send username
3. Detect Password: prompt → send password
4. Wait for shell prompt
5. Execute stty cols 200 (wide terminal, prevents 80-column wrapping)
6. Execute --init-cmd (default: unset TMOUT)

If already logged in (no login prompt detected), skips to step 5.

📄 License

MIT