serial-mcp-server

Serial MCP Server

開発者向けツールや AI エージェントで使える、状態を保持するシリアルポート用 Model Context Protocol（MCP）サーバーです。 Claude Code、Copilot を搭載した VS Code、およびあらゆる MCP 互換ランタイムで、すぐに利用できます。stdio 経由で通信し、pyserial を使用して macOS、Windows、Linux でクロスプラットフォームのシリアル通信を実現します。

例： Claude Code にシリアルポートの一覧表示、マイクロコントローラーへの接続、DTR によるリセット、ハードウェアからの起動バナーの読み取りを指示できます。

デモ

動画による解説 — シリアルデバイスへの接続、コマンドの送信、応答の読み取り、プラグインの作成を紹介します。

---

なぜこれを作ったのか

screen や minicom にコマンドをコピー＆ペーストしたり、ボーレートを推測したり、DTR を切り替えてブートローダーを起動したり、同じテスト手順を 20 回繰り返したりしたことがある方に向けたツールです。

シリアルデバイスがあり、AI エージェントにそのデバイスとやり取りさせたいとします。ポートを開き、コマンドを送信し、応答を読み取り、プロトコルをデバッグできます。このサーバーがそれを可能にします。

MCP 互換エージェントに、ポートの一覧表示、接続のオープン、読み取り、書き込み、行単位の I/O、制御線の操作といったシリアルツール一式を提供します。さらに、プロトコル仕様やデバイスプラグインも利用できるため、生のバイト列だけでなく、より高レベルなデバイスの動作についてもエージェントが推論できます。

エージェントがこれらのツールを呼び出すと、構造化された JSON が返され、次に何をすべきかを推論します。各手順でターミナルにコマンドを手入力する必要はありません。

エージェントでできること：

• 開発とデバッグ — デバイスに接続し、コマンドを送信して応答を読み取り、会話形式で問題を診断できます（起動バナー、プロンプト、エラーコードなど）。
• 新しいファームウェアで反復作業 — プロトコル仕様を追加して、コマンドセット、起動モード、出力形式の変更をエージェントに理解させることができます。
• テストフローの自動化 — DTR でデバイスをリセットし、プロンプトを待ち、コマンドシーケンスを実行して、出力を検証できます。
• 未知のデバイスの調査 — コマンドセットを試し、プロンプトを見つけ、メッセージ形式を推測できます。
• シリアル自動化の構築 — 長時間稼働するテスト環境、製造時の立ち上げ、CI でのハードウェアのスモークテストを実現できます。

---

対象ユーザー

• 組み込みエンジニア — シリアルプロトコルでの反復作業を高速化し、会話形式でデバッグし、テストシーケンスを自動化できます
• ホビイストやメーカー — 定型コードを書かずにシリアルデバイスを操作でき、簡単なプロトコルのリバースエンジニアリングをエージェントに支援させられます
• QA エンジニアやテストエンジニア — プラグインツールで再現可能なシリアルテストスイートを構築できます
• サポートエンジニアやフィールドエンジニア — 専用ツールを使わずに、シリアルデバイスの問題を対話形式で診断できます
• 研究者 — シリアルデバイスからのデータ収集を自動化し、デバイスの機能を体系的に調査できます

---

クイックスタート（Claude Code）

pip install serial-mcp-server

# Register the MCP server with Claude Code
claude mcp add serial -- serial_mcp

次に、Claude Code で以下を試してください。

「利用可能なシリアルポートを一覧表示し、115200 ボーで /dev/ttyUSB0 のポートに接続してください。」

---

エージェントにできること

接続すると、エージェントはシリアル通信のすべての機能を利用できます。

• ポートの一覧表示 — 利用可能なシリアルデバイスを確認します
• 接続の開始と終了 — ボーレート、パリティ、ストップビット、エンコーディングを設定できます
• データの読み書き — テキスト、16 進数、または base64 形式で処理します
• 行指向の I/O — テキストプロトコル向けに、readline や区切り文字までの読み取りを行います
• 制御ライン — ハードウェアリセットやブートモードへの移行に使う DTR と RTS を設定またはパルス送信します
• フラッシュ — 入力バッファと出力バッファをフラッシュします
• プロトコル仕様の添付 — デバイス固有のコマンドやデータ形式を理解します
• プラグインの使用 — 生データの読み書きの代わりに、高レベルのデバイス操作を行います
• 仕様とプラグインの作成 — 新しいデバイス向けに作成すると、今後のセッションではそのプロトコルを「知った」状態で開始できます
• PTY ミラーリング — エージェントが使用中の同じシリアルセッションに、screen、minicom、またはカスタムスクリプトを接続します

エージェントは複数ステップの手順を自動的に調整できます。たとえば、リセットを切り替え、プロンプトを待ち、初期化シーケンスを送信して、出力をストリーミングします。

概要は次のとおりです。

生シリアル通信 → プロトコル仕様 → プラグイン

まずは生シリアル通信ツールから始め、デバイスのプロトコルが理解され、再現可能になったら、より高いレイヤーに移行できます。

---

インストール（開発環境）

# Editable install from repo root
pip install -e .

# Or with uv
uv pip install -e .

MCP はプロトコルです。このサーバーは、MCP 互換のクライアントであればどれでも動作します。以下に、よく使われるクライアントのセットアップ手順を示します。

Claude Code への追加

# Standard setup
claude mcp add serial -- serial_mcp

# Or run as a module
claude mcp add serial -- python -m serial_mcp_server

# Enable all plugins
claude mcp add serial -e SERIAL_MCP_PLUGINS=all -- serial_mcp

# Enable specific plugins only
claude mcp add serial -e SERIAL_MCP_PLUGINS=mydevice,ota -- serial_mcp

# Debug logging
claude mcp add serial -e SERIAL_MCP_LOG_LEVEL=DEBUG -- serial_mcp

VS Code / Copilot への追加

プロジェクトの .vscode/mcp.json に追加します（または新規作成します）。

{
  "servers": {
    "serial": {
      "type": "stdio",
      "command": "serial_mcp",
      "args": [],
      "env": {
        "SERIAL_MCP_PLUGINS": "all"
      }
    }
  }
}

必要に応じて env を調整します。SERIAL_MCP_PLUGINS に特定のプラグイン名を設定するか、PTY ミラーリングを有効にする場合は SERIAL_MCP_MIRROR を追加してください。

Cursor への追加

プロジェクトの .cursor/mcp.json に追加します（または新規作成します）。Cursor はツール名のドットをサポートしていないため、SERIAL_MCP_TOOL_SEPARATOR を _ に設定する必要があります。

{
  "mcpServers": {
    "serial": {
      "command": "serial_mcp",
      "args": [],
      "env": {
        "SERIAL_MCP_PLUGINS": "all",
        "SERIAL_MCP_TOOL_SEPARATOR": "_"
      }
    }
  }
}

環境変数

変数	デフォルト	説明
SERIAL_MCP_MAX_CONNECTIONS	10	同時に開けるシリアル接続の最大数です。
SERIAL_MCP_PLUGINS	disabled	プラグインポリシーです。すべて許可するには all、特定のプラグインを許可するには name1,name2 を指定します。未設定の場合は無効です。
SERIAL_MCP_MIRROR	off	PTY ミラーモードです。off、ro（読み取り専用）、または rw（読み書き可能）を指定します。macOS と Linux のみ対応しています。
SERIAL_MCP_MIRROR_LINK	/tmp/serial-mcp	PTY シンボリックリンクのベースパスです。接続ごとに番号が割り当てられます。例：/tmp/serial-mcp0、/tmp/serial-mcp1 など。
SERIAL_MCP_LOG_LEVEL	WARNING	Python のログレベルです（DEBUG、INFO、WARNING、ERROR）。ログは stderr に出力されます。
SERIAL_MCP_TRACE	enabled	すべてのツール呼び出しを JSONL 形式でトレースします。無効にするには 0、false、または no を設定します。
SERIAL_MCP_TRACE_PAYLOADS	disabled	トレース対象の引数に書き込み時の data を含めます（デフォルトでは削除されます）。
SERIAL_MCP_TRACE_MAX_BYTES	16384	切り詰めるまでの最大ペイロード文字数です（TRACE_PAYLOADS が有効な場合のみ適用されます）。
SERIAL_MCP_TOOL_SEPARATOR	.	ツール名のセグメントを区切る文字です。ツール名のドットを拒否する MCP クライアント（Cursor など）では _ を設定します。

---

ツール

カテゴリ	ツール
シリアルコア	serial.list_ports、serial.open、serial.close、serial.connection_status、serial.read、serial.write、serial.readline、serial.read_until、serial.flush、serial.set_dtr、serial.set_rts、serial.pulse_dtr、serial.pulse_rts
イントロスペクション	serial.connections.list
プロトコル仕様	serial.spec.template、serial.spec.register、serial.spec.list、serial.spec.attach、serial.spec.get、serial.spec.read、serial.spec.search
トレース	serial.trace.status、serial.trace.tail
プラグイン	serial.plugin.template、serial.plugin.list、serial.plugin.reload、serial.plugin.load

---

プロトコル仕様

仕様は、接続設定、メッセージ形式、コマンド、複数ステップのフローなど、シリアルデバイスのプロトコルを記述した Markdown ファイルです。.serial_mcp/specs/ に保存され、バイトストリームの意味をエージェントに教えます。

仕様がなくても、エージェントはポートを開いてデータを送受信できます。仕様があれば、送信すべきコマンド、想定される応答、データの意味がわかります。

デバイスについてエージェントに伝えることで、仕様を作成できます。データシートを貼り付けたり、プロトコルを説明したり、デバイスを調査して見つけた内容を記録するよう任せたりできます。エージェントは仕様ファイルを生成して登録し、今後のセッションで参照します。仕様は手動で作成することもできます。

---

プラグイン

プラグインを使うと、サーバーにデバイス固有のショートカットツールを追加できます。エージェントが読み書きの生データのシーケンスを組み立てる代わりに、プラグインが mydevice.read_temp や ota.upload_firmware のような高レベルの操作を提供します。

エージェントは Python プラグインを生成することもできます（承認が必要です）。デバイスを調査し、調査結果に基づいてプラグインを作成すると、今後のセッションでショートカットツールを使えるようになります。手動でのコーディングは不要です。

プラグインを有効にするには：

# Enable all plugins
claude mcp add serial -e SERIAL_MCP_PLUGINS=all -- serial_mcp

# Enable specific plugins only
claude mcp add serial -e SERIAL_MCP_PLUGINS=mydevice,ota -- serial_mcp

読み込み済みのプラグインを編集した場合は、serial.plugin.reload を実行するだけで反映されます。再起動は不要です。

---

トレース

すべてのツール呼び出しは .serial_mcp/traces/trace.jsonl とメモリ内のリングバッファ（直近の 2000 件のイベント）に記録されます。トレースはデフォルトで有効です。無効にするには SERIAL_MCP_TRACE=0 を設定します。

イベント形式

ツール呼び出しごとに 2 つのイベントが記録されます。

{"ts":"2025-01-01T00:00:00.000Z","event":"tool_call_start","tool":"serial.read","args":{"connection_id":"s1"},"connection_id":"s1"}
{"ts":"2025-01-01T00:00:00.050Z","event":"tool_call_end","tool":"serial.read","ok":true,"error_code":null,"duration_ms":50,"connection_id":"s1"}

• connection_id は、存在する場合、引数から取得されます
• 書き込みの data は、デフォルトでトレース対象の引数から除外されます（有効にするには SERIAL_MCP_TRACE_PAYLOADS=1 を設定します）

トレースの確認

serial.trace.status を使うと設定とイベント数を確認でき、serial.trace.tail を使うと最近のイベントを取得できます。ファイルを直接読む必要はありません。

---

PTY ミラー

MCP サーバーがシリアルポートを占有している場合、ほとんどの OS では他のプロセスがそのポートを開けません。PTY ミラーを使うと仮想のクローンポートが作成され、外部ツール（screen、minicom、ロジックアナライザー、カスタムスクリプトなど）が同時に接続できます。

# Enable read-only mirror
claude mcp add serial \
  -e SERIAL_MCP_MIRROR=ro \
  -- serial_mcp

# After opening a connection, the response includes the mirror path:
# { "mirror": { "pty_path": "/dev/ttys004", "link": "/tmp/serial-mcp0", "mode": "ro" } }

# In another terminal:
screen /tmp/serial-mcp0 115200

モード	動作
off	ミラーなし（デフォルト）。MCP サーバーのみがポートにアクセスできます。
ro	外部ツールはすべてのシリアルデータを受信できますが、デバイスへの書き込みはできません。
rw	外部ツールはデータの受信とデバイスへの書き込みの両方ができます。

プラットフォーム： macOS と Linux のみです。Windows では、SERIAL_MCP_MIRROR を ro／rw に設定すると警告がログに記録され、設定は無視されます。

---

エージェントなしで試す

MCP Inspector を使ってサーバーを対話的にテストできます。Claude などのエージェントは必要ありません。

npx @modelcontextprotocol/inspector python -m serial_mcp_server

ターミナル出力に表示された認証トークンを使って URL を開きます。Inspector では、ウェブ UI から任意のツールを呼び出し、応答をリアルタイムで確認できます。

---

既知の制限事項

• 単一クライアントのみ。 サーバーが一度に処理できる MCP セッションは 1 つです（stdio トランスポート）。マルチクライアントトランスポート（HTTP/SSE）は今後追加される可能性があります。
• 排他的アクセス。 PTY ミラーを使わない場合、MCP サーバーがシリアルポートを排他的に占有する必要があります。

---

安全性

このサーバーは、AI エージェントを実際のハードウェアに接続します。それがこのサーバーの目的ですが、その分、純粋なソフトウェアツールよりもリスクが高くなります。

プラグインは任意のコードを実行します。 プラグインを有効にすると、エージェントはお使いのマシン上で、サーバーのすべての権限を使って Python コードを作成および実行できます。エージェントが生成したプラグインは、読み込む前に確認してください。すべてのプラグインを許可する代わりに、SERIAL_MCP_PLUGINS=name1,name2 を使用して、特定のプラグインのみを許可してください。

書き込み操作は実際のデバイスに影響します。 シリアルデバイスに誤ったコマンドを送信すると、意図しない動作を引き起こしたり、ほかの接続済みシステムを妨害したり、ハードウェアを損傷したりする可能性があります（フラッシュの消去、ブートローダーモードへの移行、アクチュエーターの作動など）。エージェントがアクセスできる範囲を考慮してください。

ツールの承認は慎重に行ってください。 MCP クライアントからツール呼び出しの承認を求められたら、その呼び出しを一度だけ許可するか、常に許可するかを検討してください。「常に許可」は便利ですが、エージェントがそれ以降の確認なしに同じ操作を繰り返せることを意味します。

このソフトウェアは MIT ライセンスの下で現状有姿のまま提供されます。エージェントがハードウェアに対して行うことについては、利用者が責任を負います。

---

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE をご覧ください。

謝辞

このプロジェクトは、Python でクロスプラットフォームのシリアル通信を実現する優れたライブラリ pyserial を基盤として構築されています。