Skip to main content
Glama
node-opcua-modeler-mcp-server

node-opcua-modeler-mcp-server

Official
by node-opcua

node-opcua-modeler-mcp-server

npm version npm downloads/month npm downloads total License: Apache-2.0 MCP

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.

Related MCP server: Berlin Group MCP Server

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 VS Code (GitHub Copilot)

Add to .vscode/mcp.json. VS Code's top-level key is servers, not mcpServers; a file copied from the Claude Desktop example is silently ignored.

{
  "inputs": [
    { "type": "promptString", "id": "opcua-modeler-api-key", "description": "OPC UA Modeler API key (optional)", "password": true }
  ],
  "servers": {
    "opcua-modeler": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "node-opcua-modeler-mcp-server"],
      "env": { "OPCUA_MODELER_API_KEY": "${input:opcua-modeler-api-key}" }
    }
  }
}

Click Start above the server entry, then use Copilot Chat in Agent mode with the tools ticked under the tools icon. MCP: List Servers → Show Output shows why a server failed to start.

When VS Code is connected to WSL, this server runs inside WSL and needs Node.js there. VS Code does not start it from an interactive shell, so an nvm install is not on its PATH: set command to the absolute path printed by which npx.

With any MCP client

npx node-opcua-modeler-mcp-server

The server communicates over stdio using the Model Context Protocol.

As a remote connector (Mistral, claude.ai, any streamable-HTTP client)

Use the hosted endpoint https://api.opcua-modeler.sterfive.io/mcp, or host your own with node-opcua-modeler-mcp-http (or --http), Docker, or the bundled Caddy compose file for HTTPS: see docs/http-hosting.md.

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.

Variable

Values

Purpose

OPCUA_MODELER_BACKEND

cloud (default), local

Which backend serves the model tools

OPCUA_MODELER_API_KEY

stfv_…

API key, cloud backend only

OPCUA_MODELER_API_URL

URL

Override the hosted API base URL

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.

  • serve and this MCP server must run as the same user on the same system: they talk over a named pipe or Unix socket, which cannot cross from Windows into WSL. Under WSL, start serve in a WSL terminal.

  • On Linux, macOS and WSL, serve publishes its discovery file in $XDG_RUNTIME_DIR/opcua-modeler/ and copies it to /tmp/opcua-modeler-<user>/; this server looks in both. Editors do not always pass XDG_RUNTIME_DIR to the servers they start (VS Code under WSL may not), and the copy is what lets the two meet. With an older serve, set XDG_RUNTIME_DIR in this server's env to the value it has in the terminal running serve.

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:

Call

Meaning

symbols_csv: "<previous CSV>"

Regeneration: existing nodes keep their ids. Accepts the CSV text, or the base64 symbols_csv a previous call returned.

mode: "new"

First generation: there are no symbols yet.

mode: "renumber"

Allocate new ids on purpose.

a self-contained .opcua.yaml stream

It carries its own symbol table, which is replayed.

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 <name>.model.symbols.csv, and writes <name>.Nodeset2.xml, the CSV and, with include_docs, <name>.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 an API key. On the local stdio server, pass xml_path instead of xml: the file is read by the server, so even a multi-megabyte companion spec never passes through the conversation.

→ opcua_model_reverse({ xml: "<?xml version=..." })
← {
    "yaml": "namespaces:\n  di:\n...",
    "diagnostics": []
  }

opcua_model_create ☁️

Generate an OPC UA YAML model from a natural language description using AI. The AI will auto-detect relevant companion specs, generate a validated model with documentation, and auto-correct validation errors. Requires an API key.

→ opcua_model_create({ prompt: "A robotic welding cell with two robot arms, each having 6 axes, temperature monitoring on each motor" })
← {
    "success": true,
    "yaml": "namespaces:\n  di:\n  robotics:\n...",
    "attempts": 2,
    "diagnostics": [],
    "model": "gemini-2.5-pro",
    "tokens": { "input": 4200, "output": 1800 }
  }

→ opcua_model_create({ prompt: "A CNC lathe with spindle speed and temperature", forceSpecs: ["di", "cnc"] })
← {
    "success": true,
    "yaml": "namespaces:\n  di:\n  cnc:\n...",
    "attempts": 1,
    "diagnostics": [],
    "model": "gemini-2.5-pro",
    "tokens": { "input": 3500, "output": 1200 }
  }

Coverage

Companion Specifications (33)

Alias

Specification

Types

padim

OPC UA for PA-DIM

101

ijtBase

OPC UA for IJT Base

65

machineTool

OPC UA for Machine Tools

63

scales

OPC UA for Scales

58

lads

OPC UA for Laboratory Devices

53

di

OPC UA for Devices

44

glass

OPC UA for Glass Manufacturing

36

machineVision

OPC UA for Machine Vision

36

adi

OPC UA for Analyzer Devices

35

commercialKitchenEquipment

OPC UA for Commercial Kitchen Equipment

35

i4aas

OPC UA for I4AAS

32

fxAc

OPC UA FX Automation Component

28

robotics

OPC UA for Robotics

25

fxCm

OPC UA FX Connection Manager

24

ia

OPC UA for Industrial Automation

20

amb

OPC UA for AMB

18

autoId

OPC UA for AutoID

18

iolink

OPC UA for IO-Link

16

metalForming

OPC UA for Metal Forming

16

…and 13 more

Total

32 namespaces with types

817 types

The registry holds 33 specs; irdi is a dictionary-entry namespace and defines no ObjectTypes or VariableTypes. These figures come from catalog/catalog.json and are asserted against it by test/catalog-coverage.test.ts, so they cannot drift silently.

Engineering Units

1,533 official UNECE Rec. 20 symbols plus 136 natural language aliases (e.g., "celsius" → °C, "revolutions per minute" → r/min). Every alias resolves to a symbol the modeler engine accepts — the lookup never invents one.

How It Works

The server ships with a pre-generated catalog.json containing all type information extracted from OPC Foundation's official NodeSet2.xml files via node-opcua. All queries are answered from this static catalog — no network required, no API key needed.

┌──────────────────────────────────────────────────┐
│  node-opcua-modeler-mcp-server                   │
│                                                  │
│  LOCAL TOOLS (offline, free)                      │
│  ┌────────────────────────────────────────┐       │
│  │ catalog.json (1.7 MB)                  │       │
│  │ • 33 companion spec registries         │       │
│  │ • 817 type summaries + details         │       │
│  │ • 1,533 engineering units              │       │
│  └────────────────────────────────────────┘       │
│  7 tools → query the catalog                     │
│                                                  │
│  CLOUD TOOLS (via api.opcua-modeler.sterfive.io) │
│  5 tools → reference / validate / generate /     │
│           reverse / create                       │
│                                                  │
│  stdio transport (JSON-RPC)                      │
└──────────────────────────────────────────────────┘

Use Cases

  • AI-assisted OPC UA modeling — agents can discover types, resolve dependencies, and validate unit symbols before generating YAML/XML models

  • Copilot integration — add OPC UA awareness to coding assistants

  • Industrial digital twin design — explore companion spec type hierarchies interactively

  • Learning OPC UA — ask an AI to explain types and their relationships

Requirements

  • Node.js ≥ 18

Licensing

Three layers, stated once:

What

Licence

This package (node-opcua-modeler-mcp-server, the MCP client and its catalog)

Apache License 2.0 from version 1.5.0 — see NOTICE for trademark and third-party notices. Versions 1.0–1.4.x were published under MIT and remain so.

The hosted OPC UA Modeler API (opcua-modeler.sterfive.io/api/v1) that the cloud backend calls

Sterfive API Terms of Use — anonymous discovery, free and paid plans.

The OPC UA Modeler CLI and opcua-modeler serve (the local backend)

Sterfive commercial licence — see the product page.

"OPC UA Modeler" and "Sterfive" are trademarks of Sterfive SAS; the Apache licence grants no rights to them. Contributions are accepted under the Developer Certificate of Origin.

© Sterfive SAS

Available Tools

11 tools
find_engineering_unitAInspect

Find the official UNECE Rec. 20 engineering unit symbol for a given description. ALWAYS call this before using any engineering unit — NEVER guess unit symbols.

Inputs: query (required).

find_reusable_blockAInspect

Find reusable Interfaces / AddIns by capability — pass a member name or keyword (e.g. "SerialNumber", "DeviceHealth", "Location") and get the standard blocks that already expose it. PREFER applying/composing an existing block over redefining its members inline. Interfaces are applied with interfaces:; addins (types with a DefaultInstanceBrowseName) are composed with addIns:. A single property → use the Interface; a whole named sub-object → use the AddIn.

Inputs: query (required).

get_type_detailsAInspect

Get detailed information about a specific type: its components, properties, methods, interfaces, and optional members. Use this to understand a type's structure before creating instances or subtypes.

Inputs: alias (required), browseName (required).

list_namespacesAInspect

List all well-known OPC UA companion spec namespace aliases with their full names, URIs, and dependencies. Use this to discover what namespaces are available.

Inputs: no named parameters.

list_typesAInspect

List ALL ObjectTypes, VariableTypes, and InterfaceTypes defined in a specific companion spec namespace. ALWAYS call this before using any type from a namespace — NEVER guess type names.

Inputs: alias (required).

opcua_model_createAInspect

Generate an OPC UA YAML model from a natural language description using AI. Requires an API key (set OPCUA_MODELER_API_KEY env var). The AI will auto-detect relevant companion specs, generate a validated model with documentation, and auto-correct validation errors.

Inputs: prompt (required), forceSpecs.

opcua_model_generateAInspect

Generate OPC UA NodeSet2.xml and Symbols.CSV from a YAML model. Requires an API key (set OPCUA_MODELER_API_KEY env var). Returns base64-encoded artifacts if the model is valid, or diagnostics if validation fails. Optionally set include_docs=true to also generate markdown documentation.

Inputs: yaml (required), include_docs.

opcua_model_reverseBInspect

Reverse-engineer a NodeSet2.xml file back into the YAML DSL format. Requires an API key (set OPCUA_MODELER_API_KEY env var). Optionally specify the target namespace URI to extract.

Inputs: xml (required), namespace_uri.

opcua_model_validateAInspect

Validate an OPC UA YAML model for correctness. Returns diagnostics with severity (error/warning/info), codes, messages, and line numbers. Works without an API key (limited to 50 calls/day). ALWAYS validate before generating.

Inputs: yaml (required).

resolve_dependenciesAInspect

Given one or more companion spec namespace aliases, returns the full resolved dependency list that MUST go in the YAML namespaces: section. Always call this before generating the namespaces block.

Inputs: aliases (required).

search_typesAInspect

Search for types across ALL companion specs by keyword. Use this when you don't know which namespace defines a type. Returns matching types with their namespace alias.

Inputs: query (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool serves a distinct purpose: discovering namespaces, types, blocks, and units; creating models via reverse or AI; validating and generating. No significant overlap; agents can clearly differentiate.

    Naming Consistency3/5

    Tools follow two naming patterns: verb-based (list_namespaces, resolve_dependencies, etc.) and prefix-based (opcua_model_reverse, opcua_model_create, etc.). This inconsistency may cause minor confusion.

    Tool Count5/5

    11 tools cover the full modeler workflow: discovery, creation, validation, and generation. The count is well-scoped for the domain without superfluous or missing tools.

    Completeness4/5

    Core lifecycle (discover, create, validate, generate) is covered. Missing editing or deletion of existing models, but these are not essential for the stated purpose of generating models.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects AI agents to OPC UA-enabled industrial systems for real-time monitoring and control of operational data. It enables users to read, write, and browse industrial device nodes through natural language interactions.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI assistants with contextual access to Berlin Group Open Finance API specifications, enabling specification-compliant guidance through semantic search, graph database queries, and document retrieval.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides offline access to the Brick Schema ontology, enabling validation and search of building metadata classes through MCP tools.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables LLMs to read, write, browse, search, and subscribe to live data on OPC-UA industrial automation servers, with caching, discovery index, and support for stdio or HTTP transports.
      5
      MIT