Model Context Protocol 서버로, AI 코딩 어시스턴트(Claude Code, Cursor, Windsurf 등)가 시리얼 포트 장치와 상호작용할 수 있게 해줍니다.
AI 에이전트는 시리얼 장치에 연결하고, 명령을 보내고, 출력을 캡처할 수 있습니다 — 사용자는 브라우저 기반 터미널에서 전체 과정을 실시간으로 볼 수 있습니다.
🔌 시리얼 연결 — COM 포트, /dev/ttyUSB*, /dev/ttyS* 등에 자동 로그인으로 연결
🖥️ 웹 터미널 — 실시간 시리얼 I/O를 보여주는 xterm.js 브라우저 터미널(Xshell과 유사)
🤖 MCP 서버 — 네이티브 도구 통합; AI 에이전트가 MCP 프로토콜을 통해 직접 호출
📝 타임스탬프 로그 — 모든 줄에 타임스탬프가 기록되고, 일별 로테이션되며, 터미널 표시와 정확히 일치
⌨️ 양방향 — AI가 명령을 보내고 + 사용자가 브라우저 터미널에서 수동으로 입력 가능
🌐 다국어 로그인 — 영어, 중국어, 일본어 로그인/비밀번호 프롬프트 자동 감지
⏱️ 대기 후 전송 — 특정 출력을 기다린 후 즉시 데이터 전송(예: uboot 비밀번호 창)
🛡️ 타임아웃 복구 — 타임아웃 시 자동 Ctrl+C, 세션 중단 없음
Related MCP server: UART MCP Server
pip install mcp pyserial aiohttp또는 requirements에서:
pip install -r requirements.txtClaude 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/를 참조하세요.
> 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의 시리얼 작업을 실시간으로 확인하세요.
도구 | 설명 |
| 사용 가능한 모든 시리얼 포트 장치 나열 |
| 시리얼 포트에 연결하고 웹 터미널 시작(자동 로그인 지원) |
| 셸 명령을 보내고 장치 출력 반환 |
| 원시 데이터 전송(예: Ctrl+C = |
| 특정 출력을 기다린 후 즉시 데이터 전송(시간에 민감한 작업용) |
| 현재 연결 상태 확인 |
| 타임스탬프가 있는 작업 로그 가져오기 |
| 연결 해제 및 웹 터미널 중지 |
serial_connect선택적 자동 로그인으로 시리얼 장치에 연결합니다.
매개변수 | 타입 | 기본값 | 설명 |
| str | (필수) | 시리얼 장치 이름(예: |
| int |
| 보드레이트 |
| str |
| 자동 로그인 사용자 이름(비어 있으면 건너뜀) |
| str |
| 자동 로그인 비밀번호 |
| str |
| 로그인 후 실행할 명령(세션 타임아웃 방지) |
| int |
| 웹 터미널 포트 |
serial_send셸 명령을 보내고 출력을 캡처합니다.
매개변수 | 타입 | 기본값 | 설명 |
| str | (필수) | 실행할 셸 명령 |
| int |
| 응답 타임아웃(초) |
serial_wait_send시리얼 출력에서 특정 문자열을 기다린 후 즉시 데이터를 전송합니다. 다음에 적합합니다:
재부팅 중 uboot 진입(3초 비밀번호 창)
로그인 프롬프트에 응답
"X를 기다린 후 Y를 전송"하는 모든 자동화
매개변수 | 타입 | 기본값 | 설명 |
| str | (필수) | 기다릴 대상 문자열 |
| str | (필수) | 대상이 발견되면 전송할 데이터 |
| int |
| 최대 대기 시간(초) |
| str |
| 대기 전에 보낼 선택적 데이터(예: 정적 프롬프트를 다시 트리거하려면 |
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 --list# 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"인수 | 기본값 | 설명 |
| (필수) | 시리얼 장치 이름(COM3, /dev/ttyUSB0) |
|
| 보드레이트 |
|
| 웹 서버 포트 |
| (없음) | 자동 로그인 사용자 이름 |
| (없음) | 자동 로그인 비밀번호 |
|
| 로그인 후 명령(여러 개는 |
| (자동) | 사용자 정의 프롬프트 감지 정규식 |
| — | 사용 가능한 시리얼 포트 나열 |
로그는 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 >>> 自动登录流程完成터미널 출력: timestamp content (xterm.js 버퍼에서 추출 — 브라우저 표시와 정확히 일치)
시스템 이벤트: timestamp >>> message (로그인, 시작 등)
로그 줄 충실도:
줄 바꿈 분할 없음 — 터미널에서 소프트 래핑된 줄(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 제거, 에코 제거, 프롬프트 제거)
프롬프트 감지(셸 프롬프트, 알려진 프롬프트)
로그 줄 버퍼링(백스페이스 처리, 부분 줄, ANSI 정리)
자동 로그인 키워드 감지(영어, 중국어, 일본어)
명령 송수신(모의 시리얼, 타임아웃, Ctrl+C 복구)
대기 후 전송(즉시 일치, 동적 일치, 타임아웃, 트리거)
HTML 페이지 구조(중복 ID 없음, 필수 요소)
MCP 서버 도구 등록
HTTP API 엔드포인트(상태, 전송, 원시, 로그 — 오류 처리)
보안(하드코딩된 자격 증명 없음, .gitignore 적용)
자동 로그인 흐름은 다국어 프롬프트를 지원합니다:
언어 | 로그인 프롬프트 | 비밀번호 프롬프트 |
영어 |
|
|
중국어 |
|
|
일본어 | — |
|
로그인 흐름:
Enter를 보내 터미널 깨우기
login: 프롬프트 감지 → 사용자 이름 전송
Password: 프롬프트 감지 → 비밀번호 전송
셸 프롬프트 대기
stty cols 200 실행(넓은 터미널, 80열 래핑 방지)
--init-cmd 실행(기본값: unset TMOUT)
이미 로그인된 경우(로그인 프롬프트가 감지되지 않음), 5단계로 건너뜁니다.
This server cannot be deployed
Remote Desktop Commander: use files, terminal and processes on your own computers from any AI app.
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 explicitly paired computers, servers, and VMs for permitted remote actions.
