mcp-serial-bridge

シリアル通信を介して外部デバイスを操作するための MCP(Model Context Protocol)サーバーです。 AI エージェントが list_ports / connect / write_and_read の 3 ツールを通じてシリアルポートを直接制御できます。

モデム、計測器、組み込みボード、レトロコンピュータなど、シリアルインタフェースを持つあらゆる機器を対象にできます。

前提

• ローカル MCP サーバー: このサーバーはユーザーのマシン上でローカルプロセスとして動作します。クラウドやリモートでの動作は想定していません。シリアルポートに物理的にアクセスできる PC 上で実行してください。
• Visual Studio Code (VSCode) + GitHub Copilot: MCP クライアントとして VSCode（GitHub Copilot Agent モード）を使用することを前提としています。他の MCP 対応クライアントからも利用できますが、本ドキュメントの手順は VSCode を基準に記載しています。

動作要件

• Python 3.11 以上
• macOS / Windows / Linux

セットアップ

git clone https://github.com/46nori/mcp-serial-bridge.git
cd mcp-serial-bridge

uv を使う場合（推奨）

macOS / Linux:

# uv のインストール（未インストールの場合）
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

VSCode の統合ターミナルからそのまま実行できます。外部の PowerShell を使っても問題ありません。

# uv のインストール（未インストールの場合）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Windows での注意: uv のインストール直後は、現在開いている PowerShell では uv コマンドが認識されないことがあります。 その場合は VSCode の統合ターミナルを一度閉じて開き直すか、VSCode を再起動してから続行してください。

どちらの環境でも、インストール後は新しいシェルを開き直してから以下を実行してください。

# uv が使えることを確認
uv --version

# 依存パッケージのインストールと仮想環境の作成
uv sync

venv + pip を使う場合

uv が使えない環境では標準の venv も利用できます。

macOS / Linux:

python3 -m venv .venv
.venv/bin/pip install "mcp[cli]>=1.9.0" "pyserial>=3.5"

Windows (PowerShell):

py -3 -m venv .venv
.\.venv\Scripts\pip install "mcp[cli]>=1.9.0" "pyserial>=3.5"

どちらの方法でも仮想環境は .venv/ に作成されます。

Linux でシリアルポートへのアクセス権がない場合は、ユーザーを dialout グループに追加してください。

sudo usermod -aG dialout $USER
# 反映には再ログインが必要

サーバーの起動

.vscode/mcp.json はリポジトリに含まれています。 macOS / Linux ではそのまま利用できます。 Windows では Python の実行ファイルの場所が異なるため、command を .venv/Scripts/python.exe に変更してください。

コマンドパレット（Cmd+Shift+P / Ctrl+Shift+P）から MCP: Restart Server を実行すると serial-bridge が利用可能になります。

設定ファイルの詳細は技術詳細を参照してください。

---

使用例

ユーザーはツールを直接呼び出しません。 AI エージェント（GitHub Copilot）に自然言語で指示を出すと、AI が必要なツールを判断して順番に呼び出します。

操作の流れ:
  ユーザー → 自然言語で指示 → AI エージェント → MCP ツール → シリアルデバイス

結果は AI の返答としてチャットに表示されます。

汎用 AT コマンド機器（モデム・Wi-Fi モジュールなど）

ユーザーが AI に伝える内容:

「シリアルポートを確認して、AT コマンドデバイスに 9600bps・改行コード CR+LF で接続し、AT コマンドで疎通確認と AT+GMR でバージョンを取得してください」

AI が内部で呼び出すツールの引数（参考）:

{ "name": "list_ports", "arguments": {} }
{ "name": "connect",        "arguments": { "port": "/dev/cu.usbserial-10", "baudrate": 9600, "line_ending": "\r\n" } }
{ "name": "write_and_read", "arguments": { "command": "AT",     "wait_for": "OK", "timeout": 3 } }
{ "name": "write_and_read", "arguments": { "command": "AT+GMR", "wait_for": "OK", "timeout": 5 } }

---

計測器・センサー（CR のみ）

ユーザーが AI に伝える内容:

「COM3 に 115200bps で接続して（改行は CR のみ）、READ? コマンドで計測値を取得してください」

AI が内部で呼び出すツールの引数（参考）:

{ "name": "connect",        "arguments": { "port": "COM3", "baudrate": 115200, "line_ending": "\r" } }
{ "name": "write_and_read", "arguments": { "command": "READ?", "wait_for": "\n", "timeout": 2 } }

---

Linux/Raspberry Pi シリアルコンソール（LF のみ）

ユーザーが AI に伝える内容:

「/dev/ttyUSB0 に 115200bps で接続して（改行は LF のみ）、uname -a を実行してください」

AI が内部で呼び出すツールの引数（参考）:

{ "name": "connect",        "arguments": { "port": "/dev/ttyUSB0", "baudrate": 115200, "line_ending": "\n" } }
{ "name": "write_and_read", "arguments": { "command": "uname -a", "wait_for": "$", "timeout": 5 } }

---

通信のモニタリング

本サーバーは MCP ローカルサーバーのため、stdout は JSON-RPC プロトコル専用です。 通信の観測には以下の3つの手段を使い分けます。

┌────────────────────────────────────────────────────┐
│  AI エージェント (VSCode)                           │
│      ↕ stdout/stdin  (JSON-RPC 2.0専用)            │
│  mcp-serial-bridge                                  │
│      ├─ stderr  → VSCode Output パネル              │
│      ├─ logs/serial_YYYYMMDD.log  → 詳細ログ        │
│      └─ logs/rx_stream.log  → RX 生ストリーム       │
└────────────────────────────────────────────────────┘

stderr — VSCode Output パネル

MCP サーバーの stderr は VSCode の Output パネル（serial-bridge チャンネル）に表示されます。 すべての送受信と接続イベントが方向付きで出力されます。

[SYS] Connected to /dev/cu.usbserial-110 at 19200 baud
[TX] AT\r
[RX] AT\r\nOK\r\n

特徴: VSCode が付加するタイムスタンプが入るため、長い通信では見づらくなることがあります。

---

logs/serial_YYYYMMDD.log — 詳細ログ

すべての TX / RX / SYS イベントをタイムスタンプ付きでファイルに記録します。 改行・制御文字はエスケープ済みのため、後から通信手順を正確に追跡できます。

[2026-03-10T12:34:56.123] [SYS] Connected to /dev/cu.usbserial-110 at 19200 baud
[2026-03-10T12:34:57.001] [TX] AT\r
[2026-03-10T12:34:57.089] [RX] AT\r\nOK\r\n

用途: デバッグ・通信手順の記録など

---

logs/rx_stream.log — RX 生ストリーム

デバイスから受信した生データのみをタイムスタンプなしでファイルに追記します。
(データはUTF-8に変換されます)

通信内容をリアルタイムに表示したい場合：

touch logs/rx_stream.log
tail -f logs/rx_stream.log

さらにファイルにキャプチャしたい場合:

tail -f logs/rx_stream.log | tee logs/session_$(date +%H%M%S).log

用途: 純粋なシリアルモニタとして使う・機器の出力を記録する

ツールリファレンス

list_ports

現在接続されているシリアルポートの一覧を返します。 connect を呼ぶ前に必ず実行し、使用する device 名を確認してください。

macOS では、カーネル内部用の /dev/tty.* は除外し、アプリ用の /dev/cu.* のみを返します。

戻り値の例:

[
  {
    "device": "/dev/cu.usbserial-110",
    "description": "USB2.0-Serial",
    "hwid": "USB VID:PID=1A86:7523"
  }
]

---

connect

指定したポートにシリアル接続します。すでに接続中の場合は安全に切断してから再接続します。

引数	型	既定値	説明
port	string	必須	list_ports で取得した device 名
baudrate	int	19200	通信速度 (bps)
line_ending	string	"\r"	コマンド末尾に付加する改行コード

line_ending の選び方:

値	意味	主な用途
"\r"	CR only（既定）	組み込み機器・レガシーシリアル機器
"\r\n"	CR+LF	Windows 系機器・一部のモデムや計測器
"\n"	LF only	Linux/UNIX シェル・現代的な機器

接続後に変更する場合は connect を再実行してください（write_and_read に個別指定はできません）。

---

write_and_read

コマンドを送信し、応答を受信して返します。事前に connect が必要です。

引数	型	既定値	説明
command	string	必須	送信するコマンド文字列
wait_for	string	""	この文字列が受信に現れるまで待機
timeout	float	5.0	最大待機時間（秒）

• wait_for を省略した場合、データの受信が途切れた時点で即座に返ります。
• プロンプト文字列（例: "> ", "OK", "#"）を指定することで、機器が応答し終わるまで正確に待機できます。
• 送信前に受信バッファをクリアするため、前コマンドの残データが混入しません。

---

技術詳細

VSCode MCP 設定ファイル

.vscode/mcp.json はリポジトリに含まれており、VSCode が自動で読み込みます。${workspaceFolder} 変数は VSCode が実行時に展開するため、手動でのパス展開は不要です。

macOS / Linux:

{
  "servers": {
    "serial-bridge": {
      "type": "stdio",
      "command": "${workspaceFolder}/.venv/bin/python",
      "args": ["${workspaceFolder}/src/server.py"]
    }
  }
}

Windows:

{
  "servers": {
    "serial-bridge": {
      "type": "stdio",
      "command": "${workspaceFolder}/.venv/Scripts/python.exe",
      "args": ["${workspaceFolder}/src/server.py"]
    }
  }
}

Windows で uv や .venv を作成した直後に反映されない場合は、VSCode の統合ターミナルを開き直すか MCP: Restart Server を再実行してください。

MCP プロトコル

AI とサーバー間は MCP (JSON-RPC 2.0) over stdio で通信します。たとえば connect の呼び出しは以下のような JSON になります。ユーザーがこの JSON を書く必要はありません。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "connect",
    "arguments": {
      "port": "/dev/cu.usbserial-10",
      "baudrate": 9600,
      "line_ending": "\r\n"
    }
  }
}

他の MCP 対応クライアントから使用する

type: stdio に対応した任意の MCP クライアントから利用できます。VSCode の ${workspaceFolder} 変数は使えないため、絶対パスで指定してください。

Claude Desktop の例 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "serial-bridge": {
      "command": "/Users/yourname/mcp-serial-bridge/.venv/bin/python",
      "args": ["/Users/yourname/mcp-serial-bridge/src/server.py"]
    }
  }
}

クライアント	設定ファイルのパス
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Cursor	.cursor/mcp.json またはグローバルの ~/.cursor/mcp.json