OPC UA Modeler

node-opcua-modeler-mcp-server

An MCP server that gives AI agents access to the OPC UA companion specification type system — 817 types across 33 industrial namespaces, plus 1,533 engineering units — and lets agents validate, generate, reverse-engineer, and create OPC UA information models.

Built on node-opcua, the most widely used OPC UA stack for Node.js.

Why?

When an AI agent needs to build an OPC UA information model, it must know:

• What companion spec types exist (DI, Machinery, Robotics, Machine Tools…)
• What components, properties, and methods each type has
• What namespace dependencies are required
• What engineering unit symbols are valid (UNECE Rec. 20)

This MCP server answers all of those questions — offline, for free, in milliseconds.

Quick Start

With Claude Desktop

Add to your claude_desktop_config.json:

{

"mcpServers": { "opcua-modeler": { "command": "npx", "args": ["-y", "node-opcua-modeler-mcp-server"], "env": { "OPCUA_MODELER_API_KEY": "stfv_your_api_key_here" } } } }

Note: The API key is optional for discovery tools (offline) and opcua_model_validate (50 anonymous calls/day). It is required for opcua_model_generate, opcua_model_reverse, and opcua_model_create. Register at opcua-modeler.sterfive.io and create a key under Settings → API — the free tier gives 25 calls/day for 90 days; see pricing for paid plans.

With any MCP client

npx node-opcua-modeler-mcp-server

The server communicates over stdio using the Model Context Protocol.

Using a local backend instead of the hosted API

If you run the OPC UA Modeler CLI on the same machine, the model tools can be served from it instead of the hosted API — your YAML never leaves the host.

Start the server (requires a licence that includes the serve entitlement):

opcua-modeler serve

Then set one environment variable in your MCP client config:

{

"mcpServers": { "opcua-modeler": { "command": "npx", "args": ["-y", "node-opcua-modeler-mcp-server"], "env": { "OPCUA_MODELER_BACKEND": "local" } } } }

No API key is needed in this mode — the client discovers the local endpoint and its credentials automatically.

Notes

• The two backends are never mixed, and there is no fallback between them. If local is selected and no server is running, the call fails with instructions rather than silently sending your model to the hosted API.
• The seven discovery tools are local to this package and work offline on either setting.
• opcua_model_create (AI generation) is available on the cloud backend only.

Tools

list_namespaces

List all 33 OPC UA companion spec namespaces with aliases, URIs, and dependencies.

→ list_namespaces()

← [ { "alias": "di", "name": "OPC UA for Devices", "uri": "http://opcfoundation.org/UA/DI/", "dependencies": [] }, { "alias": "robotics", "name": "OPC UA for Robotics", "uri": "http://opcfoundation.org/UA/Robotics/", "dependencies": ["di", "ia"] }, ... ]

resolve_dependencies

Resolve the full dependency chain for companion spec aliases. Returns a topologically sorted list for the YAML namespaces: block.

→ resolve_dependencies({ aliases: ["machineTool"] })

← ["di", "ia", "machinery", "isa95JobControl", "machineryJobs", "machineTool"]

list_types

List all ObjectTypes and VariableTypes defined in a companion spec namespace.

→ list_types({ alias: "robotics" })

← [ { "browseName": "MotionDeviceType", "kind": "ObjectType", "subtypeOf": "di:ComponentType", ... }, { "browseName": "AxisType", "kind": "ObjectType", "subtypeOf": "di:ComponentType", ... }, ... ] // 25 types

get_type_details

Get the full structure of a type — components, properties, methods, interfaces, including inherited members.

→ get_type_details({ alias: "robotics", browseName: "MotionDeviceType" })

← { "browseName": "MotionDeviceType", "kind": "ObjectType", "subtypeOf": "di:ComponentType", "interfaces": ["di:IVendorNameplateType", "di:ITagNameplateType"], "components": [ { "browseName": "robotics:Axes", "nodeClass": "Object", "typeDefinition": "FolderType", "modellingRule": "Mandatory" }, { "browseName": "robotics:PowerTrains", "nodeClass": "Object", "typeDefinition": "FolderType", "modellingRule": "Mandatory" }, ... ], "properties": [ { "browseName": "di:Manufacturer", "dataType": "LocalizedText", "modellingRule": "Mandatory" }, { "browseName": "robotics:MotionDeviceCategory", "dataType": "MotionDeviceCategoryEnumeration", "modellingRule": "Mandatory" }, ... ] }

search_types

Search for types across all companion specs by keyword.

→ search_types({ query: "temperature" })

← [ { "alias": "glass", "browseName": "MotorTemperatureTooHighEventType", ... }, { "alias": "padim", "browseName": "TemperatureMeasurementVariableType", ... }, { "alias": "amb", "browseName": "OverTemperatureConditionClassType", ... } ]

find_reusable_block

Find reusable Interfaces and AddIns by capability — pass a member name or keyword and get the standard blocks that already expose it. Prefer composing an existing block over redefining its members by hand.

→ find_reusable_block({ query: "SerialNumber" })

← [ { "browseName": "di:IVendorNameplateType", "alias": "di", "kind": "interface", "matchedMembers": ["di:SerialNumber"], "members": ["di:Manufacturer", "di:Model", "di:SerialNumber", ...] }, { "browseName": "machinery:MachineIdentificationType", "alias": "machinery", "kind": "addin", "matchedMembers": ["di:SerialNumber"], "members": ["machinery:Location", "di:SerialNumber", ...] } ]

kind tells you how to apply it: interface goes in interfaces:, addin in addIns:.

find_engineering_unit

Find the official UNECE Rec. 20 engineering unit symbol. Supports fuzzy matching and natural language aliases.

→ find_engineering_unit({ query: "celsius" })

← { "symbol": "°C", "matchType": "alias", "confidence": 1 }

→ find_engineering_unit({ query: "revolutions per minute" }) ← { "symbol": "r/min", "matchType": "alias", "confidence": 1 }

→ find_engineering_unit({ query: "bar" }) ← { "symbol": "bar", "matchType": "exact", "confidence": 1 }

get_dsl_reference ☁️

Fetch the YAML DSL grammar reference — the file header, top-level sections, type and instance syntax, and a list of common mistakes. No API key required.

Served from the API rather than bundled into this package, so the reference an agent reads always matches the validator that will judge its output.

→ get_dsl_reference()

← { "version": "1", "reference": "# OPC UA Modeler YAML DSL ..." }

opcua_model_validate ☁️

Validate an OPC UA YAML model for correctness. Returns diagnostics with severity, codes, messages, and line numbers. Works without an API key (limited to 50 calls/day per IP).

→ opcua_model_validate({ yaml: "namespaces:\n  di:\n..." })

← { "valid": true, "diagnostics": [ { "severity": "warning", "code": "W001", "message": "...", "line": 42 } ] }

By path (local stdio server only). Pass model_path instead of yaml. With OPCUA_MODELER_BACKEND=local, the model's imports: then resolve from its own folder (beside it, then deps/), as in VS Code: an import that names only a uri: needs this, because a model sent as text resolves against the folder opcua-modeler serve was started in. The hosted connector never takes paths.

→ opcua_model_validate({ model_path: "C:/models/cip/cip-example.model.yaml" })

opcua_model_generate ☁️

Generate OPC UA NodeSet2.xml and the symbols CSV from a validated YAML model. Requires an API key.

Keep NodeIds stable. The symbols CSV records the NodeId given to every node. A regeneration that does not pass it back allocates new ids, which breaks every server and client bound to the old ones. So each call must say what it is:

A call with none of these is refused before reaching the backend with SYMBOLS_DECISION_REQUIRED, and the message says how to retry.

By path (local stdio server only). Pass model_path instead of yaml. The server reads the model and its paired .model.symbols.csv, and writes .Nodeset2.xml, the CSV and, with include_docs, .md beside the model (or into output_dir): the same files and bytes as opcua-modeler generate. Unchanged files are not touched. Nothing large passes through the conversation: for the demoRobot sample the result is about 700 characters instead of about 71 KB of base64. include_artifacts: "inline" also returns the artefacts. With OPCUA_MODELER_BACKEND=local, the model's deps/ folder is resolved too. The hosted connector never takes paths.

→ opcua_model_generate({ model_path: "models/pump.model.yaml" })

← { "valid": true, "mode": "update", "symbols_source": "paired-file", "symbols": { "reused": 41, "new": 1, "dropped": 0, "renumbered": 0, "match": 1, "new_names": ["Pump_Temperature"], "dropped_names": [] }, "files": [ { "role": "nodeset", "path": ".../pump.model.Nodeset2.xml", "bytes": 54210, "status": "written" }, { "role": "symbols", "path": ".../pump.model.symbols.csv", "bytes": 1312, "status": "written" } ], "diagnostics": [], "hints": [{ "code": "SYMBOLS_UPDATED", "level": "info", "message": ".../pump.model.symbols.csv updated: 1 new id(s) (Pump_Temperature)." }], "next_steps": ["Commit pump.model.Nodeset2.xml, pump.model.symbols.csv with the model."] }

As text. Pass yaml; the artefacts come back base64-encoded in artifacts.nodeset2_xml / artifacts.symbols_csv, with the same symbols, hints and next_steps.

Hint codes: INVALID, IDS_RENUMBERED, IDS_DROPPED, SYMBOLS_LOW_MATCH (the CSV passed probably belongs to another model), SAVE_SYMBOLS, SYMBOLS_UPDATED, STREAM_TABLE_NOT_UPDATED, WARNINGS_PRESENT, PREFER_STREAM. Refusal codes: SYMBOLS_DECISION_REQUIRED, SYMBOLS_REQUIRED, SYMBOLS_FILE_EXISTS, MODE_CONFLICT.

opcua_model_reverse ☁️

Reverse-engineer a NodeSet2.xml file back into the YAML DSL format. Requires