Modbus Mcp

Modbus MCP サーバー

Model Context Protocol（MCP） に対応した軽量なサーバーで、安全かつ標準化された方法で LLM エージェントを Modbus デバイスに接続します。AI 主導のワークフローをビルディングオートメーション（BAS）や産業用制御（ICS）システムとシームレスに統合し、エージェントがリアルタイムのセンサーデータを監視し、デバイスを制御し、複雑な自動化タスクを連携して実行できるようにします。

はじめに

uv を使って Modbus MCP サーバーをプロジェクトの依存関係として追加・管理するか、uv pip install または pip install で直接インストールしてください。インストール手順の詳細については、ドキュメントのインストールセクションを参照してください。

uv add modbus-mcp

サーバーはアプリケーションに組み込んで、そこから直接実行できます。デフォルトでは、http://127.0.0.1:8000/mcp/ に Streamable HTTP エンドポイントを公開します。

# app.py
from modbus_mcp import ModbusMCP

mcp = ModbusMCP()

if __name__ == "__main__":
    mcp.run(transport="http")

ソースコードを変更せずに、付属の CLI を使ってコマンドラインから起動することもできます。

modbus-mcp

または、uvx を使って一時的な隔離環境で実行できます。詳細については、ツールの使用ガイドを参照してください。

uvx modbus-mcp

設定

プログラマブルロジックコントローラー（PLC）や Modbus ゲートウェイなど、ほとんどの操作が特定のデバイスを対象とする用途では、接続設定（host、port、unit）を環境変数で実行時に指定できます。これにより、接続パラメーターが明示されていないプロンプトはすべて、このデバイスにルーティングされます。

export MODBUS_MCP_MODBUS__HOST=10.0.0.1
export MODBUS_MCP_MODBUS__PORT=502
export MODBUS_MCP_MODBUS__UNIT=1

これらの設定は、作業ディレクトリの .env ファイルにも指定できます。

# .env
modbus_mcp_modbus__host=10.0.0.1
modbus_mcp_modbus__port=502
modbus_mcp_modbus__unit=1

複数のデバイスを操作する場合は、作業ディレクトリの devices.json ファイルで、各デバイスの接続パラメーター（host、port、unit）に固有の name を割り当てられます。プロンプトでは、この name を使ってデバイスを指定できます。

{
  "devices": [
    {"name": "Boiler", "host": "10.0.0.3", "port": 503, "unit": 3},
    {"name": "Valve", "host": "10.0.0.4", "port": 504, "unit": 4}
  ]
}

MCP Inspector

サーバーが起動していることを確認し、利用可能なリソースやツールを調べるには、MCP Inspector を起動して、Modbus MCP サーバー（http://127.0.0.1:8000/mcp/）に接続してください。トランスポートには Streamable HTTP を設定してください。

npx @modelcontextprotocol/inspector

基本概念

Modbus MCP サーバーは FastMCP で構築され、その中核となる構成要素（リソーステンプレート、ツール、プロンプト）を活用して、定型コードを最小限に抑えた、すっきりとした Python らしいインターフェースで Modbus の読み取りと書き込みを効率化します。

レジスターの読み取り

デバイス上の各レジスターはリソース（およびツールとして公開）に対応付けられます。リソーステンプレートを使って、接続の詳細（host、port、unit）と読み取りパラメーター（address、count）を指定します。

@mcp.resource("tcp://{host}:{port}/{address}?count={count}&unit={unit}")
@mcp.tool(
    annotations={"title": "Read Registers", "readOnlyHint": True, "openWorldHint": True}
)
async def read_registers(
    host: str = settings.modbus.host,
    port: int = settings.modbus.port,
    address: int = 40001,
    count: int = 1,
    unit: int = settings.modbus.unit,
) -> int | list[int]:
    """Reads the contents of one or more registers on a remote unit."""
    ...

レジスターの書き込み

書き込み操作はツールとして公開され、同じ接続の詳細（host、port、unit）を受け取ります。1 回のアトミックな呼び出しで、1 つ以上の holding registers または coils の内容を設定できます。

@mcp.tool(
    annotations={
        "title": "Write Registers",
        "readOnlyHint": False,
        "openWorldHint": True,
    }
)
async def write_registers(
    data: list[int],
    host: str = settings.modbus.host,
    port: int = settings.modbus.port,
    address: int = 40001,
    unit: int = settings.modbus.unit,
) -> str:
    """Writes data to one or more registers on a remote unit."""
    ...

認証

Streamable HTTP トランスポートで組み込みの AuthKit プロバイダーを使って認証を有効にするには、.env ファイルに AuthKit のドメインとリダイレクト URL を指定してください。詳細については、AuthKit プロバイダーのセクションを参照してください。

対話型プロンプト

構造化された応答メッセージは、やり取りを導き、不足しているパラメーターを明確にし、エラーを適切に処理するためのプロンプトを使って実装されています。

@mcp.prompt(name="modbus_help", tags={"modbus", "help"})
def modbus_help() -> list[Message]:
    """Provides examples of how to use the Modbus MCP server."""
    ...

以下は、サーバーとのやり取りに使用できるテキスト入力の例です。

Please read the value of register 40001 on 127.0.0.1:502.
Set register 40005 to 123 on host 192.168.1.10, unit 3.
Write [1, 2, 3] to holding registers starting at address 40010.
What is the status of input register 30010 on 10.0.0.5?

例

examples フォルダーには、さまざまなクライアント API を使って LLM にツールとコンテキストを提供する、Modbus MCP サーバーとの連携方法を示すサンプルプロジェクトが含まれています。

• openai-agents - OpenAI Agents SDKを使って Modbus MCP サーバーに接続する方法を示しています。
• openai - OpenAI Python libraryのリモート MCP サーバー対応を活用する最小限のアプリです。
• pydantic-ai - PydanticAI Agent Frameworkを使って Modbus MCP サーバーに接続する方法を示しています。

Docker

Modbus MCP サーバーは、次のように Docker コンテナとしてデプロイできます。

docker run -d \
  --name modbus-mcp \
  --restart=always \
  -p 8080:8000 \
  --env-file .env \
  ghcr.io/ezhuk/modbus-mcp:latest

ホストのポート 8080 をコンテナ内の MCP サーバーのポート 8000 に割り当て、存在する場合は .env ファイルから設定を読み込みます。

ライセンス

サーバーはMIT Licenseのもとでライセンスされています。