mcp-serial-bridge
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-serial-bridgeList serial ports, connect to /dev/ttyUSB0 at 115200 baud, and run uname -a"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-bridgeuv を使う場合(推奨)
macOS / Linux:
# uv のインストール(未インストールの場合)
curl -LsSf https://astral.sh/uv/install.sh | shWindows (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 syncvenv + 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
指定したポートにシリアル接続します。すでに接続中の場合は安全に切断してから再接続します。
引数 | 型 | 既定値 | 説明 |
| string | 必須 |
|
| int |
| 通信速度 (bps) |
| string |
| コマンド末尾に付加する改行コード |
line_ending の選び方:
値 | 意味 | 主な用途 |
| CR only(既定) | 組み込み機器・レガシーシリアル機器 |
| CR+LF | Windows 系機器・一部のモデムや計測器 |
| LF only | Linux/UNIX シェル・現代的な機器 |
接続後に変更する場合は connect を再実行してください(write_and_read に個別指定はできません)。
write_and_read
コマンドを送信し、応答を受信して返します。事前に connect が必要です。
引数 | 型 | 既定値 | 説明 |
| string | 必須 | 送信するコマンド文字列 |
| string |
| この文字列が受信に現れるまで待機 |
| float |
| 最大待機時間(秒) |
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) |
|
Claude Desktop (Windows) |
|
Cursor |
|
Available Tools
3 toolsconnectA
指定したシリアルポートに接続する。
port には list_ports で取得した device 名を指定する。
すでに接続中の場合は、内部で既存接続を閉じてから再接続する。
Args:
port: 接続ポート名 (例: /dev/cu.usbserial-10, COM3)
baudrate: 通信速度 (default: 19200)
line_ending: コマンド末尾に付加する改行コード
"
" (CR only, default) " " (CR+LF) " " (LF only)
| Name | Required | Description | Default |
|---|---|---|---|
| port | Yes | ||
| baudrate | No | ||
| line_ending | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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: 最大待機時間(秒)
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | ||
| timeout | No | ||
| wait_for | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
3 tool updates
v0.1.0- First observed
connect - First observed
list_ports - First observed
write_and_read
TDQS
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.
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.
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.
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
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
Give AI agents real phone numbers, messages, and voice calls via MCP.
Protocol-native energy infrastructure orchestration for AI data centers. Provides 46 MCP tools across 8 grid protocols (IEC-61850, DNP3, Modbus, OCPP, OpenADR, IEEE 2030.5, IEC 60870-5-104, ICCP) with 5 core API primitives: connect, dispatch, settle, comply, and intel. Enables AI agents to programmatically interact with substations, grid interfaces, and energy assets for real-time workload-grid coordination.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
471
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI assistants to communicate with serial port devices, supporting port management, data transmission in text/binary modes, interactive terminal sessions, and automatic reconnection.1412MIT
- AlicenseAqualityDmaintenanceAllows 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.2718MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to communicate with UART/serial devices, offering tools for port management, data read/write, and protocol handling.MIT
- AlicenseAqualityCmaintenanceLets 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.71MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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