Serial Web Terminal MCP
Serial Web Terminal MCP
一个模型上下文协议服务器，让 AI 编程助手（Claude Code、Cursor、Windsurf 等）能够与串口设备交互。
AI 代理可以连接串口设备、发送命令并捕获输出——而用户可以通过浏览器终端实时观看整个过程。
✨ 功能特性
🔌 串口连接 — 连接 COM 端口、
/dev/ttyUSB*、/dev/ttyS*等，支持自动登录🖥️ Web 终端 — 基于 xterm.js 的浏览器终端，实时显示串口 I/O（类似 Xshell）
🤖 MCP 服务器 — 原生工具集成；AI 代理通过 MCP 协议直接调用
📝 带时间戳的日志 — 每行日志均带有时间戳，每日轮转，与终端显示完全一致
⌨️ 双向交互 — AI 发送命令 + 用户可在浏览器终端中手动输入
🌐 多语言登录 — 自动检测英文、中文和日文的登录/密码提示符
⏱️ 等待并发送 — 等待特定输出后立即发送数据（例如 uboot 密码窗口）
🛡️ 超时恢复 — 超时时自动发送 Ctrl+C，无挂起会话
📦 安装
pip install mcp pyserial aiohttp或从 requirements 安装：
pip install -r requirements.txt🚀 快速开始
1. 配置你的 AI 客户端
Claude Code（项目根目录下的 .mcp.json 或 ~/.claude/claude_config.json）：
{
"mcpServers": {
"serial-terminal": {
"command": "python",
"args": ["/path/to/serial_mcp_server.py"]
}
}
}Cursor（设置 → MCP → 添加服务器）：
{
"mcpServers": {
"serial-terminal": {
"command": "python",
"args": ["/path/to/serial_mcp_server.py"]
}
}
}参见
examples/获取可直接使用的配置文件。
2. 与你的 AI 助手交流
> 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在浏览器中打开 http://localhost:8080 实时观看 AI 的串口操作。
🔧 MCP 工具
工具 | 描述 |
| 列出所有可用的串口设备 |
| 连接串口并启动 Web 终端（支持自动登录） |
| 发送 shell 命令并返回设备输出 |
| 发送原始数据（例如 Ctrl+C 为 |
| 等待特定输出，然后立即发送数据（用于时间关键型操作） |
| 检查当前连接状态 |
| 获取带时间戳的操作日志 |
| 断开连接并停止 Web 终端 |
serial_connect
连接串口设备，支持可选自动登录。
参数 | 类型 | 默认值 | 描述 |
| str | (必填) | 串口设备名称（例如 |
| int |
| 波特率 |
| str |
| 自动登录用户名（留空则跳过） |
| str |
| 自动登录密码 |
| str |
| 登录后执行的命令（防止会话超时） |
| int |
| Web 终端端口 |
serial_send
发送 shell 命令并捕获输出。
参数 | 类型 | 默认值 | 描述 |
| str | (必填) | 要执行的 shell 命令 |
| int |
| 响应超时时间（秒） |
serial_wait_send
等待串口输出中出现特定字符串，然后立即发送数据。适用于：
重启时进入 uboot（3 秒密码窗口）
响应登录提示符
任何“等待 X，然后发送 Y”的自动化场景
参数 | 类型 | 默认值 | 描述 |
| str | (必填) | 要等待的目标字符串 |
| str | (必填) | 当找到目标时要发送的数据 |
| int |
| 最大等待时间（秒） |
| str |
| 可选：在等待前发送的数据（例如 |
🖥️ 独立使用（无需 MCP）
serial_web.py 可通过 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 --listHTTP 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 参数
参数 | 默认值 | 描述 |
| (必填) | 串口设备名称（COM3, /dev/ttyUSB0） |
|
| 波特率 |
|
| Web 服务器端口 |
| (无) | 自动登录用户名 |
| (无) | 自动登录密码 |
|
| 登录后命令（多个命令用 |
| (自动) | 自定义提示符检测正则表达式 |
| — | 列出可用串口 |
📝 日志格式
日志保存到 logs/serial_YYYYMMDD.log（每日轮转）：
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 >>> 自动登录流程完成终端输出：
时间戳 内容（从 xterm.js 缓冲区提取——与浏览器显示完全一致）系统事件：
时间戳 >>> 消息（登录、启动等）
日志行保真度：
无换行拆分 — 被终端软换行（80列换行）的行被合并回单一逻辑行
进度条感知 —
\r覆盖序列（10%\r20%\r30%）被折叠为最终可见状态（30%）退格感知 — 使用退格键进行的手动编辑被记录为最终编辑后的行
每行始终带有时间戳前缀
🏗️ 架构
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)📁 项目结构
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🧪 测试
运行回归测试套件（无需物理串口设备）：
python tests/test_regression.py -v测试覆盖：
输出清理（去除 ANSI、回显移除、提示符移除）
提示符检测（shell 提示符、已知提示符）
日志行缓冲（退格处理、部分行、ANSI 清理）
自动登录关键词检测（英语、中文、日语）
命令发送/接收（模拟串口、超时、Ctrl+C 恢复）
等待并发送（即时匹配、动态匹配、超时、触发）
HTML 页面结构（无重复 ID、必要元素）
MCP 服务器工具注册
HTTP API 端点（状态、发送、原始、日志——错误处理）
安全（无硬编码凭据、.gitignore 覆盖）
🌐 自动登录
自动登录流程支持多语言提示符：
语言 | 登录提示符 | 密码提示符 |
英语 |
|
|
中文 |
|
|
日语 | — |
|
登录流程：
发送 Enter 唤醒终端
检测到
login:提示符 → 发送用户名检测到
Password:提示符 → 发送密码等待 shell 提示符
执行
stty cols 200（宽终端，防止 80 列换行）执行
--init-cmd（默认：unset TMOUT）
如果已登录（未检测到登录提示符），则跳过步骤 2-4，直接从步骤 5 开始。
📄 许可证
This server cannot be installed
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Live browser debugging for AI assistants — DOM, console, network via MCP.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/WakkeWang/serial-terminal-mcp-tool'
If you have feedback or need assistance with the MCP directory API, please join our Discord server