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

serial_connect

Connect to a serial device with optional auto-login.

serial_send

Send a shell command and capture output.

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

🖥️ 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

📝 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:

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