Serial MCP

UART および USB シリアルアクセス用の serial-mcp

serial-mcp は、シリアルポートへ直接アクセスするための MCP サーバーです。UART または USB シリアルのデータを読み書きし、マイクロコントローラー、Arduino ボード、STM32 チップ、その他の組み込み機器とのデータストリーミングを行います。読み取りでは、シリアルモニター上でブロックする代わりに、タイムアウトとパターンマッチングを使用します。

サーバーは常時 RX キャプチャを提供します。line、delimiter、length-prefixed、start/end、SLIP、COBS の各形式を使用して、TX フレームと RX フレームをデコードします。また、AT、JSON、shell、NMEA-0183、Modbus ASCII のパーサーも提供します。

プロトコルプリセットはチェックサム検証に対応しています。サーバーは、自動再接続、イベントログ、DTR/RTS、BREAK、フロー制御もサポートします。MCP クライアントは、これらの機能をシリアルブートローダー、リセット、組み込みボードで利用できます。

クイックスタート

1. サーバーをインストールします。Cargo、Nix、ビルド済みバイナリのオプションについては、インストールを参照してください。
2. エージェントを接続します。エージェント設定ガイドに従うか、以下の例を使用してください。
3. デバイスを検出します。list_ports() を呼び出して、profile_matches を確認します。結果には、引数なしの open で再利用される設定が表示されます。
4. ポートを開きます。ポートのみを指定して open(port=...) を呼び出します。 ボーレートはデフォルトで 115200/8-N-1 です。既知のデバイスには、最後に使用された信頼度の高いプロファイルを再利用します。新しいデバイスには、永続的な生成プロファイルを作成します。
5. デバイスと通信します。コマンドと応答のやり取りには transact() を使用します。バッファー済みデータや非同期データには read() を使用します。送信のみの操作には write() を使用します。

機能

ツール一覧（25 ツール）

リソースとプロンプト

インストール

Cargo（すべてのプラットフォーム）

cargo install serial-mcp

Nix

nix profile install github:qarnet/serial-mcp

ビルド済みバイナリ

ツールチェーンは不要です。各リリースでは、プラットフォームごとにバイナリが1つ公開されます。 latest/download の URL は最新リリースを参照します。

Linux では、ポートにアクセスできるよう、ユーザーを dialout グループに追加します。

sudo usermod -aG dialout $USER

エージェントを接続する

クライアントごとのセットアップについては、エージェント設定ガイドを参照してください。 Claude Code CLI、Claude Desktop、Cursor、VS Code、Zed、opencode、 Codex、Hermes、HTTP トランスポートについて説明しています。

{
  "mcpServers": {
    "serial": {
      "type": "stdio",
      "command": "serial-mcp",
      "args": ["--allowlist=/dev/ttyACM*,/dev/ttyUSB*"]
    }
  }
}

基本的なワークフロー

一般的な作業では、次の手順で進めます。ポートを検出し、開き、通信し、学習した プロファイルを確認してから、必要に応じて高度なツールを使用します。

1. list_ports() を呼び出します。profile_matches の各項目は ports に対応しています。
   • selected は、引数なしの open が selected_profile を再利用することを意味します。
   • ambiguous は、同じ順位のプロファイルが複数あるため open_profile が必要であることを意味します。
   • duplicate、ineligible、none は、引数なしの open で新規または一時的なプロファイルが開始されることを意味します。
2. 引数なしの open(port=...) を呼び出します。結果には profile バインディングが含まれます。バインディングには、名前、ソース、信頼度、永続性、生成済みフラグ、リビジョン、変更状態が示されます。
3. transact(data=..., match=..., timeout_ms=...) を使うと、1回の呼び出しでデータを書き込んで応答を待ち受けます。バッファー済みデータや要求されていないデータには read() を使います。
4. reconfigure、set_flow_control、または接続モードの configure の後に、 profile_persistence を確認します。値は persisted、not_needed、 transient、または failed です。更新された profile バインディングも確認します。
5. close() を呼び出します。正常に閉じる際は、安全対策として変更状態のバインディングを再試行します。

起動時やリセット時のキャプチャには、capture_boot を呼び出します。Arduino の自動リセット、 電源再投入時のバナー、起動プロンプトに対応します。

この呼び出しでは、未読の OS 入力が消去されます。RX のライブエッジがマークされます。DTR/RTS をパルス出力することもでき、その場合は確実に解除されます。マーク後のバイトのみを専用カーソルでキャプチャします。結果はメモリ内に制限付きで保持され、ファイルには書き込まれません。from カーソルのモデルについては、RX と読み取りを参照してください。プロファイルの動作については、デバイスプロファイルを参照してください。

プロトコル

protocol フィールドでは、送受信の両方向にフレーミングとパーサーのデフォルトを指定します。 NMEA と Modbus ASCII のプリセットではチェックサムが検証されます。

フィールドの優先順位は、明示的に指定した呼び出しフィールド、呼び出し時のプリセット、接続のデフォルト、 接続プリセットの順です。プロトコルガイドでは、この 順序、チェックサムの動作、フレーミングとパーサーのリファレンスについて説明しています。

主な概念とガイド

トランスポートとオプション

serial-mcp [OPTIONS]

  --transport <stdio|http>          Transport to use (default: stdio)
  --allowlist <patterns>            Comma-separated glob patterns for allowed ports
  --bind <addr>                     HTTP bind address (default: 127.0.0.1:8000)
  --max-program-buffered-bytes <N>  Global budget for all in-flight RX tools
  --max-tool-buffered-bytes <N>     Per-tool ceiling for max_buffered_bytes
  --profiles-path <path>            Profile store file path (default: OS user config dir + serial-mcp/profiles.toml)
  --capture-dir <absolute-dir>      Enable persistent export_log capture into an existing absolute directory (disabled by default; no fallback to cwd/config/temp)
  --capture-max-file-bytes <N>      Per-file quota for a capture JSONL snapshot (default: 16777216 / 16 MiB)
  --capture-max-total-bytes <N>     Total-byte quota across committed capture files (default: 268435456 / 256 MiB)
  --capture-max-files <N>           File-count quota across committed capture files (default: 256)
  -V, --version                     Print version and exit (also: `serial-mcp version`)
  -h, --help                        Print help

  RUST_LOG                   Log level env var (error/warn/info/debug/trace)

プロファイルストアは、すべてのセッションで共有される 1 つの TOML ファイルです。分離されたストアを使用するには、--profiles-path を指定してください。デバイスプロファイルを参照してください。

永続キャプチャ

export_log は、--capture-dir のルートにポータブルな .jsonl ファイル名で書き込みます。任意のパスは受け付けず、ファイルを上書きすることもありません。永続キャプチャを参照してください。

MCP 互換性

serial-mcp は MCP 2025-11-25 をサポートしています。このバージョンでは従来のセッションライフサイクルを使用します。

MCP 2026-07-28 もサポートしています。このバージョンでは、SEP-2549 のキャッシュフィールドを使用する最新のディスカバリーとステートレスリクエストを採用しています。stdio と HTTP の両トランスポートで、ポートの許可リストをサポートしています。

CI では、公式の適合性チェックと Inspector の相互運用性チェックを実行します。検証ツールはコミット済みの npm ロックファイルから取得します。CI は npm ci --ignore-scripts でインストールします。ツールはローカルのバイナリとして実行し、npx 経由では実行しません。

実際の旧バージョン rmcp 1.7.0 クライアントを使い、HTTP と stdio で後方互換性をテストします。ローカルと CI の完全なバージョンゲートは、次のコマンドで実行してください。

bash scripts/test-mcp-compat.sh

開発

プッシュまたはプルリクエストの作成前に、cargo fmt --all を実行してください。CI では最初に、独立した Ubuntu のフォーマットジョブで cargo fmt --all -- --check を 1 回実行します。フォーマットに失敗すると、後続のコストの高い Nix、ビルド／テスト／Clippy、および MCP 適合性ジョブがブロックされます。

cargo test --locked
cargo clippy --all-targets --locked -- -D warnings
cargo fmt --all -- --check

# Linux-only required Rust PTY fixture suites
cargo test --locked --test device_fixture -- --test-threads=1
cargo test --locked --test device_command_parity -- --test-threads=1
cargo test --locked --test device_framing_parity -- --test-threads=1
cargo test --locked --test device_protocol_parity -- --test-threads=1
cargo test --locked --test device_parity_repeat public_boundary_repeat_gate -- --ignored --test-threads=1

本番環境の経路を使う実 PTY フィクスチャテストは Linux で実行します。macOS と Windows では、通常の Rust のビルド／テスト／Clippy に加え、制御されたバックエンドのカバレッジを実行します。

ドキュメントとステータス

製品バックログでは、計画中および進行中の作業を追跡しています。ドキュメントの目次からは、ユーザーガイド、リファレンス仕様、レポートを参照できます。 問題や機能リクエストはトラッカーに報告してください。

• CHANGELOG.md
• AGENTS.md、コントリビューター向けガイドライン

MCP レジストリ

このパッケージは、次の名前で MCP レジストリから入手できます。

mcp-name: io.github.qarnet/serial-mcp

ライセンス

MIT。LICENSEを参照してください。