OPC-UA MCP Server

OPC-UA MCP サーバー

LLM が stdio または HTTP 経由で OPC-UA 産業オートメーションサーバーのライブデータを読み取り、書き込み、ブラウズ、検索、サブスクライブできる MCP サーバーです。永続キャッシュと、アドレス空間の検索可能なインデックスを内蔵しています。

https://github.com/user-attachments/assets/0b676e6e-17ce-42f5-918f-9a615e939008

クイックスタート

同梱の Microsoft OPC-UA テストサーバーと、Claude がアクセスできる公開トンネルを使って、最初から最後まで最も手早く動作を確認する方法です。

git clone https://github.com/mwieczorkiewicz/opcua-mcp.git
cd opcua-mcp
make compose-up        # starts a test OPC-UA server, opcua-mcp, and a public HTTPS tunnel
make connector-url      # prints a URL like https://xyz.trycloudflare.com/mcp

その URL を Claude の Settings → Connectors → Add custom connector に貼り付けてから、サーバーのブラウズや値の読み取りを依頼します。完了したら make compose-down で停止してください。このトンネルで公開される内容や、代わりに独自の OPC-UA サーバーに接続する方法については、docs/deployment.md を参照してください。

ローカルでのビルドと実行

go build -o opcua-mcp ./cmd/opcua-mcp.go

# stdio (default) - no OPC-UA connection until the client calls opcua_connect
./opcua-mcp

# HTTP - connects eagerly at startup
SERVER_TRANSPORT=http OPCUA_ENDPOINT=opc.tcp://localhost:4840 ./opcua-mcp

Go 1.26 以降が必要です。テストサーバー／コンテナ化されたデプロイには、任意で Docker も必要です。

機能

• 読み取り／書き込み：ノード値の読み取りと書き込みに対応します。書き込み時には型を検証し、型が一致しない値がデバイスに送信される前に拒否します。
• ブラウズ：アドレス空間を一階層ずつ、または再帰的にブラウズできます。ノード ID ではなく名前でノードを検索することもできます。
• サブスクライブ：プッシュ型のライブ更新に対応します。サブスクリプションは再起動後も維持され、再接続時に自動的に再確立されます。
• キャッシュ：読み取り結果、ブラウズ結果、型情報をディスク（bbolt）にキャッシュするため、繰り返しの検索でデバイスへの往復通信が発生しません。書き込み時には該当するエントリーが自動的に無効化されます。
• 検出と検索：アドレス空間をバックグラウンドで検出し、部分一致やあいまい検索によるブラウズ名の検索に対応するため、Bleve でインデックス化します。
• 認証：匿名認証、ユーザー名／パスワード認証、証明書認証に対応し、OPC-UA のセキュリティポリシーとモードを設定できます。

キャッシュレイヤー、サブスクリプションマネージャー、検出インデックスの連携については、docs/architecture.md を参照してください。

MCP ツール

ツール	説明
opcua_read	1 つ以上のノード値を読み取ります。サブスクライブ済みのノードはライブキャッシュから提供されます。それ以外のノードは、max_age_ms でキャッシュ値を許可しない限り、ライブで読み取ります。
opcua_write	ノードに値を書き込みます。書き込み前に、値の型をノードの型と照合して検証します。
opcua_get_value	単一ノードの値を読み取ります。opcua_read の便利なラッパーです。
opcua_get_value_by_name	検出インデックスを介して、ノード ID ではなくブラウズ名で値を読み取ります。
opcua_browse	ノードの直下の子ノードを一覧表示します。
opcua_browse_nodes	ノードから深さの上限まで再帰的にブラウズし、子ノードを親ノードの下にネストして表示します。
opcua_node_info	ノードのメタデータ（データ型、アクセスレベルなど）を取得します。
opcua_find_similar_nodes	検出インデックスを使って、ブラウズ名をあいまい一致で検索します。
opcua_subscribe	指定した間隔で、1 つ以上のノードのプッシュ型更新を開始します。
opcua_unsubscribe	ID を指定するか、対象ノードの名前を指定してサブスクリプションをキャンセルします。
opcua_list_subscriptions	有効なサブスクリプションを一覧表示します。
opcua_connect / opcua_disconnect	接続を明示的に管理します（主に stdio モードで使用します）。
opcua_server_info	OPC-UA サーバーのメタデータを取得します。
opcua_discovery_stats	バックグラウンドの検出キャッシュの統計情報（ノード数、深さの分布、有効フラグ）を取得します。
opcua_force_discovery	次のサイクルを待たずに、検出の更新をただちに実行します。
opcua_debug_search / opcua_ensure_server_nodes	ノードが検索結果に表示されない原因を調査するための診断ツールです。

MCP リソース

リソース	説明
opcua://node/{node_id}	ノードデータです。例：opcua://node/ns=2;i=1。複数のノードには、カンマ区切りのリストを指定できます。
opcua://server	OPC-UA サーバー情報です。

設定

設定は、優先順位の低い順に次の3つのソースから読み込まれます（viper を使用）。

1. 組み込みのデフォルト値（以下の表を参照）。
2. 任意の設定ファイル（TOML、YAML、JSON、または viper がサポートするその他の形式）。デフォルトでは、存在する場合に ./config.{yaml,yml,toml,json,...} が読み込まれます。明示的なパスを指定するには CONFIG_FILE=/path/to/config.toml を設定してください。設定ファイルは完全に任意です。環境変数だけでも引き続き十分です。
3. 環境変数（SERVER_*、OPCUA_*、MCP_*、SEARCH_*、STORE_*）。設定ファイルよりも常に優先されるため、環境変数のみを使用する既存のデプロイも変更なしで引き続き動作します。

設定ファイルでは、環境変数名を小文字にし、各プレフィックスの下にネストして記述します。たとえば、SERVER_HTTP_PORT は次のようになります。

server:
  http_port: "8080"

サーバー

変数	デフォルト	説明
SERVER_TRANSPORT	stdio	stdio または http
SERVER_HTTP_PORT	8080	HTTP トランスポートのポート
SERVER_LOG_LEVEL	info	debug、info、warn、error
SERVER_LOG_FORMAT	json	json または text
SERVER_LOG_OUTPUT	stdout	stdout、stderr、または file（stdio モードでは stdout が MCP ストリームを伝送するため、stderr に強制されます）
SERVER_LOG_FILE	-	ログファイルのパス。SERVER_LOG_OUTPUT=file の場合は必須です
SERVER_LOG_ADD_SOURCE	false	ログエントリーにソースファイル名と行番号を追加します

OPC-UA 接続

変数	デフォルト	説明
OPCUA_ENDPOINT	opc.tcp://localhost:4840	サーバーのエンドポイント
OPCUA_AUTH_MODE	anonymous	anonymous、username、または certificate
OPCUA_USERNAME / OPCUA_PASSWORD	-	AUTH_MODE=username の場合は必須です
OPCUA_CERT_FILE / OPCUA_KEY_FILE	-	AUTH_MODE=certificate の場合は必須です
OPCUA_SERVER_CERT	-	サーバー証明書ファイルのパス
OPCUA_SECURITY_POLICY	None	None、Basic128Rsa15、Basic256、Basic256Sha256、Aes128_Sha256_RsaOaep
OPCUA_SECURITY_MODE	None	None、Sign、SignAndEncrypt
OPCUA_REQUEST_TIMEOUT	30s	リクエストごとのタイムアウト
OPCUA_SESSION_TIMEOUT	60s	セッションのタイムアウト
OPCUA_MAX_RETRIES	3	接続の再試行回数
OPCUA_RETRY_DELAY	1s	再試行までの待機時間

MCP

変数	デフォルト	説明
MCP_NAME	OPC-UA MCP Server	クライアントに通知するサーバー名
MCP_VERSION	1.0.0	クライアントに通知するサーバーのバージョン
MCP_ENABLE_TOOLS	true	ツールを有効にします
MCP_ENABLE_RESOURCES	true	リソースを有効にします
MCP_ENABLE_PROMPTS	false	プロンプトを有効にします
MCP_HTTP_PATH	/mcp	HTTP エンドポイントのパス

検出と検索

変数	デフォルト	説明
SEARCH_ENABLE_DISCOVERY	true	バックグラウンドでのノード検出を有効にします
SEARCH_DISCOVERY_INTERVAL	30s	アドレス空間を再クロールする間隔
SEARCH_DISCOVERY_ROOT_NODE	i=85	クロールの起点となるルートノード（Objects フォルダー）
SEARCH_MAX_DISCOVERY_DEPTH	10	最大クロール深度
SEARCH_MAX_NODES_PER_BROWSE	10000	ブラウズ呼び出しで返されるノード数の上限
SEARCH_ENABLE_SEARCH	true	Bleve 検索インデックスを有効にします
SEARCH_INDEX_PATH	./search_index	検索インデックスのディレクトリ
SEARCH_MAX_RESULTS	100	検索ごとの最大結果数
SEARCH_MIN_SCORE	0.1	最小一致スコア
SEARCH_ENABLE_CACHE	true	リードスルーキャッシュの有効・無効を切り替えます。false にすると、すべての opcua_read／opcua_write／opcua_browse_nodes 呼び出しが常にライブで実行され、キャッシュ導入前とまったく同じ動作になります

永続ストア

オンディスクの bbolt データベースを使用して、読み取り時キャッシュとサブスクリプションの永続化を実現します。

変数	デフォルト	説明
STORE_DB_PATH	mcp_opcua_store.db	データベースファイルのパス
STORE_OPEN_TIMEOUT	5s	ファイルを開く際にロック解除を待つ時間
STORE_TYPEINFO_TTL	24h	キャッシュされた型情報の有効期間
STORE_BROWSE_TTL	5m	キャッシュされたブラウズ結果の有効期間
STORE_BATCH_WINDOW	25ms	サブスクリプション通知をストアにフラッシュする頻度
STORE_BATCH_MAX_ITEMS	250	1 バッチでフラッシュする通知の最大数
STORE_NOTIFY_CHAN_BUFFER	1024	受信するサブスクリプション通知のバッファーサイズ

ストアを開けない場合（前回の正常でないシャットダウンによる古いロックや、読み取り専用ファイルシステムなど）、サーバーは警告をログに記録して動作を続けます。この場合、キャッシュは無効になり、サブスクリプションツールはエラーを返します。それ以外のすべてのツールには影響しません。

テレメトリー

opcua-mcp は、このオープンソースプロジェクトの保守の優先順位付けに役立てるため、匿名の集計利用状況テレメトリー（使用されたツール、キャッシュヒット率、エラーのカテゴリ）を収集します。ノード ID、エンドポイント URL、ノード値、認証情報は収集しません。デフォルトで有効です。収集内容の詳細については、docs/telemetry.md を参照してください。

次のいずれかを設定してオプトアウトできます。

変数	効果
DO_NOT_TRACK=1	プロジェクトをまたいで使われるコミュニティ標準の設定（consoledonottrack.com）
OPCUA_MCP_TELEMETRY=false	このプロジェクト独自の設定

Docker

docker build -t opcua-mcp .
docker run -p 8080:8080 -e SERVER_TRANSPORT=http -e OPCUA_ENDPOINT=opc.tcp://your-server:4840 opcua-mcp

Chainguard の最小 Go イメージを使用したマルチステージビルドで、scratch から実行します。シェルがなく、攻撃対象領域が小さい構成です。再起動後も検出、キャッシュ、サブスクリプションの状態を保持するには、./search_index と ./mcp_opcua_store.db をボリュームとしてマウントしてください。認証モードの使用例、Compose 開発スタック、Claude コネクターのトンネル設定については、docs/deployment.md を参照してください。

開発

make start-opcua-server      # Microsoft OPC-UA test server in Docker
make run-with-test-server    # run the app against it (auto start/stop)

go test ./...                # unit tests
go test -race ./...
make test-integration        # real Subscribe/reconnect/cache behavior via testcontainers-go (needs Docker)

VS Code の起動構成は .vscode/launch.example.json にあります。.vscode/launch.json にコピーすると、テストサーバーを自動的に起動・停止する stdio／HTTP／認証のデバッグターゲットを利用できます。make help で利用可能なすべてのターゲットを確認できます。

テストはテーブル駆動方式で、稼働中またはシミュレーションサーバーではなく、opcuaClient インターフェースの境界（internal/opcua/mock_client_test.go）で OPC-UA クライアントをモックします。テスト対象の各要素がどのように連携するかについては、docs/architecture.md を参照してください。また、このリポジトリのコミットメッセージ形式については、docs/COMMIT_CONVENTION.md を参照してください。

コントリビューション

フォークして変更を加え、PR を作成してください。詳細は CONTRIBUTING.md を参照してください。

ライセンス

MIT