Skip to main content
Glama
deenesjakoruzh
WakkeWang

Serial Web Terminal MCP

by WakkeWang
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Serial Web Terminal MCP

Python 3.11+ License: MIT MCP Compatible

Model Context Protocol サーバーで、AIコーディングアシスタント（Claude Code、Cursor、Windsurfなど）にシリアルポートデバイスとの対話機能を提供します。

AIエージェントはシリアルデバイスに接続し、コマンドを送信し、出力を取得できます。ユーザーはブラウザベースのターミナルを通じてプロセス全体をリアルタイムで監視できます。

✨ 機能

  • 🔌 シリアル接続 — COMポート、/dev/ttyUSB*、/dev/ttyS*などに接続し、自動ログイン対応

  • 🖥️ ウェブターミナル — 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ツール

ツール

説明

serial_list_ports

利用可能なシリアルポートデバイスをすべて一覧表示

serial_connect

シリアルポートに接続し、ウェブターミナルを起動（自動ログイン対応）

serial_send

シェルコマンドを送信し、デバイスの出力を返す

serial_raw

生データを送信（例: Ctrl+C = \x03）

serial_wait_send

特定の出力を待ち、その後即座にデータを送信（時間重視の操作向け）

serial_status

現在の接続状態を確認

serial_log

タイムスタンプ付きの操作ログを取得

serial_disconnect

切断し、ウェブターミナルを停止

serial_connect

シリアルデバイスに接続（オプションで自動ログイン）。

パラメータ

型

デフォルト

説明

port

str

(必須)

シリアルデバイス名（例: COM3、/dev/ttyUSB0）

baudrate

int

115200

ボーレート

login_user

str

""

自動ログインユーザー名（空欄の場合はスキップ）

login_pass

str

""

自動ログインパスワード

init_cmd

str

unset TMOUT

ログイン後に実行するコマンド（セッションタイムアウト防止）

web_port

int

8080

ウェブターミナルのポート

serial_send

シェルコマンドを送信し、出力を取得。

パラメータ

型

デフォルト

説明

command

str

(必須)

実行するシェルコマンド

timeout

int

8

応答タイムアウト（秒）

serial_wait_send

シリアル出力で特定の文字列を待ち、その後即座にデータを送信。以下のような場合に最適：

  • 再起動中にubootに入る（3秒のパスワードウィンドウ）

  • ログインプロンプトへの応答

  • 「Xを待ち、Yを送信」という任意の自動化

パラメータ

型

デフォルト

説明

wait_for

str

(必須)

待機対象の文字列

send_data

str

(必須)

対象が見つかったときに送信するデータ

timeout

int

60

最大待機時間（秒）

trigger

str

""

待機前に送信するオプションデータ（例: \r\n で静的なプロンプトを再トリガー）

🖥️ スタンドアロン使用（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 --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引数

引数

デフォルト

説明

--port

(必須)

シリアルデバイス名（COM3、/dev/ttyUSB0）

--baud

115200

ボーレート

--web-port

8080

ウェブサーバーポート

--login-user

(なし)

自動ログインユーザー名

--login-pass

(なし)

自動ログインパスワード

--init-cmd

unset TMOUT

ログイン後のコマンド（複数ある場合は ; で区切る）

--prompt-regex

(自動)

カスタムプロンプト検出用正規表現

--list

—

利用可能なシリアルポートを一覧表示

📝 ログ形式

ログは 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桁折り返し）は、1つの論理行にマージ

  • プログレスバー対応 — \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エンドポイント（status、send、raw、log — エラーハンドリング）

  • セキュリティ（ハードコードされた認証情報なし、.gitignoreのカバレッジ）

🌐 自動ログイン

自動ログインフローは多言語プロンプトに対応：

言語

ログインプロンプト

パスワードプロンプト

英語

login:

Password:

中国語

登录: 用户名:

口令: 密码:

日本語

—

パスワード:

ログインフロー：

  1. Enterキーを送信してターミナルを起動

  2. login: プロンプトを検出 → ユーザー名を送信

  3. Password: プロンプトを検出 → パスワードを送信

  4. シェルプロンプトを待機

  5. stty cols 200 を実行（ワイドターミナル、80桁折り返し防止）

  6. --init-cmd を実行（デフォルト: unset TMOUT）

既にログインしている場合（ログインプロンプトが検出されない場合）、ステップ5にスキップします。

📄 ライセンス

MIT

This server cannot be installed

-
license - not tested
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

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

  • GitHub

    Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.

  • sncro

    Live browser debugging for AI assistants — DOM, console, network via MCP.

  • Hint-Services-obsidian-github-mcp

    Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…

View all MCP Connectors

Latest Blog Posts

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