Skip to main content
Glama
46nori

mcp-serial-bridge

by 46nori

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 を基準に記載しています。

Related MCP server: Serial MCP Server

動作要件

  • 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

Available Tools

3 tools
connectA
指定したシリアルポートに接続する。
port には list_ports で取得した device 名を指定する。
すでに接続中の場合は、内部で既存接続を閉じてから再接続する。

Args:
    port: 接続ポート名 (例: /dev/cu.usbserial-10, COM3)
    baudrate: 通信速度 (default: 19200)
    line_ending: コマンド末尾に付加する改行コード
        "

" (CR only, default) " " (CR+LF) " " (LF only)

ParametersJSON Schema
NameRequiredDescriptionDefault
portYes
baudrateNo
line_endingNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of disclosing behavior. It transparently states that if already connected, the tool internally closes the existing connection and reconnects—a key behavioral trait. It does not cover error handling or side effects, but the disclosed behavior is valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized with a concise summary and an Args list. All sentences provide relevant information. Minor distraction comes from the slightly awkward formatting of line_ending options with backtick-enclosed line breaks, but overall it is well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a connect tool, the description covers the essential behavioral context (prerequisite of list_ports, reconnection behavior) and parameter details. An output schema exists, so not explaining return values is acceptable. The description is adequate and leaves no major gaps for its simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must fully compensate. It does so by explaining each parameter: port with examples (/dev/cu.usbserial-10, COM3), baudrate as communication speed with default 19200, and line_ending as the newline code appended to commands with allowed values (CR, CR+LF, LF). This adds clear meaning beyond the bare schema titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states '接続する' (connect) to a specified 'シリアルポート' (serial port), which is a specific verb and resource. It distinguishes from sibling tools list_ports and write_and_read by focusing on establishing the connection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs to use the port name from list_ports, implying a workflow sequence. It also notes that an existing connection is closed before reconnecting, which is a usage consideration. However, it does not explicitly state when not to use the tool or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_portsA

接続されているすべてのシリアルポートの情報を返す。 connect の呼び出し前に必ず実行し、利用可能なポート(device名)を確認すること。 macOSでは /dev/cu.* を優先的に返す(/dev/tty.* はカーネル内部用のため除外)。

Returns: list of dict with keys: - device: OS固有の識別子 (例: COM3, /dev/cu.usbserial-10) - description: デバイス名 - hwid: ハードウェアID (VID:PID)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It reveals that on macOS, /dev/cu.* ports are prioritized and /dev/tty.* is excluded, and it details the exact output structure (device, description, hwid), going beyond a basic statement of function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is succinct and well-structured: a one-sentence purpose, a usage directive, a platform nuance, and a Returns block. Each sentence earns its place with no redundancy, and the most critical information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple zero-parameter tool with an output schema, the description is complete. It covers purpose, usage, platform behavior, and return format, providing the agent with all necessary context to select and invoke the tool correctly. No gaps are evident.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the input schema is empty. Per the rubric, a baseline of 4 is appropriate when no parameters exist, and the description does not need to add any parameter semantics beyond what the schema already covers (100% coverage).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns information about all connected serial ports, using the specific verb '返す' (returns) and resource 'シリアルポート' (serial ports). It is unambiguous and distinct from sibling tools like connect and write_and_read, which perform actions rather than listing ports.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs users to run this tool before calling connect ('connect の呼び出し前に必ず実行し'), providing clear when-to-use guidance. It also adds platform-specific behavior for macOS, enhancing the agent's ability to invoke it correctly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

write_and_readA

シリアルポートにコマンドを送信し、応答を受信して返す。 事前に connect を実行しておくこと。 行末には connect で設定した line_ending が自動付加される。 wait_for にプロンプト文字列(例: "> ")を指定すると、 その文字列が受信データに現れるまで待機する。 送受信データはすべてログファイルに記録される。

Args: command: 送信する文字列 wait_for: この文字列が出現するまで受信を待機する(省略可) timeout: 最大待機時間(秒)

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYes
timeoutNo
wait_forNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that line_ending is auto-appended, wait_for causes waiting for a prompt string, and all data is logged. These behavioral details go beyond the schema and are valuable for the agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: a clear main action, then prerequisites, behavioral notes, and an Args list. It is not overly verbose and every part adds necessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description, combined with the presence of an output schema, provides sufficient context for effective use. It covers prerequisites, behavior, and side effects like logging, though it leaves return value format to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, but the description's Args section fully explains each parameter: command, wait_for, and timeout, including optionality and meaning. This completely compensates for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool sends a command to a serial port, receives a response, and returns it. It also specifies the prerequisite of connecting, distinguishing it from sibling tools like list_ports and connect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs to execute connect beforehand, providing clear sequential context. It does not explicitly name alternatives or exclusions, but the purpose and sibling names make the appropriate usage scenario evident.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv0.1.0
    • First observedconnect
    • First observedlist_ports
    • First observedwrite_and_read

TDQS

A4.5/5.0
Disambiguation5/5

Each tool has a clearly distinct role: list_ports enumerates available ports, connect establishes the connection, and write_and_read performs communication over an established connection. There is no overlap or ambiguity between tools.

Naming Consistency4/5

Tool names are mostly consistent with a verb-oriented style, but 'connect' is a bare verb while 'list_ports' and 'write_and_read' are compound verb phrases. This is a minor deviation and does not cause confusion.

Tool Count5/5

Three tools is perfectly scoped for a serial bridge: discover ports, connect, and exchange data. Each tool is necessary and there are no redundant or extraneous tools.

Completeness4/5

The core lifecycle (list, connect, communicate) is covered. Minor gaps include the lack of an explicit disconnect operation and limited options for serial parameters (baudrate and line ending only), but these do not break the primary workflow.

Maintenance

ActivityInactive
ResponsivenessNo issues

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

Related MCP Servers

  • A
    license
    A
    quality
    C
    maintenance
    Enables AI assistants to communicate with serial port devices, supporting port management, data transmission in text/binary modes, interactive terminal sessions, and automatic reconnection.
    14
    12
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    Allows AI agents to interact with serial devices via RS232/UART, enabling port listing, connection, read/write, control line manipulation, and protocol specification for automated debugging and testing.
    27
    18
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to communicate with UART/serial devices, offering tools for port management, data read/write, and protocol handling.
    MIT
  • A
    license
    A
    quality
    C
    maintenance
    Lets AI assistants read, command, and debug microcontrollers over a serial connection via MCP. Provides tools for serial port discovery, reading serial output, sending commands, and decoding register values.
    7
    1
    MIT

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/46nori/mcp-serial-bridge'

If you have feedback or need assistance with the MCP directory API, please join our Discord server