OPC UA MCP Server

August 8, 2026 · View on GitHub

The OPC UA MCP Server exposes all OPC UA Part 4 service calls as Model Context Protocol (MCP) tools. This enables AI assistants — Claude, GitHub Copilot, VS Code Copilot, Cursor, and any MCP-compatible client — to connect to OPC UA servers and interact with industrial automation systems through natural language.

What It Does

The MCP server wraps the OPC UA .NET Standard client library, translating between JSON-based MCP tool calls and OPC UA binary protocol operations. The server exposes tools through a tool profile — a named, bounded catalog selected at startup — rather than a single fixed tool count. The default full profile currently registers every tool below; running a narrower profile (core, services, administration, pubsub, or diagnostics) exposes only the subset relevant to that workflow. The tables below list the complete tool surface, organized by OPC UA Part 4 service set:

Service Set	Tools	Description
Connection	`GetEndpoints`, `Connect`, `Disconnect`, `GetConnectionStatus`	Endpoint discovery and session lifecycle management
Attribute	`Read`, `Write`, `HistoryRead`, `HistoryUpdate`	Read/write node attributes and historical data
View	`Browse`, `BrowseNext`, `TranslateBrowsePaths`, `RegisterNodes`, `UnregisterNodes`, `QueryFirst`, `QueryNext`	Navigate and query the address space
Node Management	`AddNodes`, `AddReferences`, `DeleteNodes`, `DeleteReferences`	Modify the address space
Method	`Call`	Invoke OPC UA methods
Subscription	`CreateSubscription`, `ModifySubscription`, `SetPublishingMode`, `Publish`, `Republish`, `DeleteSubscriptions`, `TransferSubscriptions`	Manage notification subscriptions
MonitoredItem	`CreateMonitoredItems`, `ModifyMonitoredItems`, `SetMonitoringMode`, `SetTriggering`, `DeleteMonitoredItems`	Monitor data changes and events
Discovery	`FindServers`, `FindServersOnNetwork`, `RegisterServer`, `RegisterServer2`	Discover servers and register
PKI Management	`ListCertificates`, `TrustCertificate`, `RemoveCertificate`, `GetPkiStorePaths`	Manage certificate trust lists
Configuration	`GetConfiguration`, `SetTransportConfiguration`, `SetClientConfiguration`, `SetSecurityConfiguration`, `SetConfiguration`	View/modify in-memory client settings; `SetConfiguration` is the `full`-profile compatibility tool
NodeSet Export	`ExportNodeSet`, `ExportNodeSetPerNamespace`	Export address space to NodeSet2 XML
Convenience	`ReadValue`, `ReadValues`, `WriteValue`, `BrowseAll`, `CallMethod`, `ReadNode`, `Cancel`	Simplified high-level operations
Packet Capture	`list_interfaces`, `start_capture`, `stop_capture`, `list_captures`, `get_capture`, `capture_now`, `list_active_channels`, `dump_keys`, `decode_pcap_with_keys`, `summarize_service_calls`, `replay_pcap`, `stop_replay`, `list_replays`	OPC UA-aware packet capture, offline decode, service-call summaries, replay

All OPC UA types (NodeId, DataValue, Variant, StatusCode, etc.) are represented as JSON for LLM-friendly interaction. Variant serialization dispatches by BuiltInType, so scalar defaults such as Boolean false and numeric 0 remain JSON false / 0 instead of being confused with Variant.Null.

The packet-capture tools are described in detail in Diagnostics. For convenience the per-tool surface is:

Tool	Description	Parameters
`list_interfaces`	Enumerates NICs available to SharpPcap.	None
`start_capture`	Starts a capture session.	`source`; optional interface, filter, endpoint, limits, folder
`stop_capture`	Stops an active session and finalizes artifacts.	`sessionId`
`list_captures`	Lists capture sessions.	Optional `state`
`get_capture`	Returns an artifact or formatted analysis.	`sessionId`, `format`, optional packet/partial controls
`capture_now`	Starts, waits, stops, and returns output.	Capture options plus output `format`
`list_active_channels`	Lists in-process secure channels with current tokens.	None
`dump_keys`	Emits keylog data.	Optional `sessionId`, `format`, `includeExpired`
`decode_pcap_with_keys`	Decodes an existing pcap and keylog offline.	`pcapPath`, `keylogPath`, `format`, optional `maxFrames`
`summarize_service_calls`	Reports service counts, latency, and errors.	`sessionId` or `pcapPath` + `keylogPath`, optional `top`
`replay_pcap`	Replays as a mock server or mock client.	`pcapPath`, `keylogPath`, `mode`, endpoints, `speed`
`stop_replay`	Stops an active replay session.	`sessionId`
`list_replays`	Lists active and recently-completed replay sessions.	None

Tool Profiles

The server selects its tool catalog through a tool profile — a bounded set of tool classes registered at startup. Profiles let a client request only the tools it needs (smaller catalogs are easier for an LLM to reason about and reduce prompt size), while full preserves the complete surface for clients that want everything.

Profile	Tool classes registered	Typical use case
`core`	Configuration, Connection, Convenience	Minimal footprint: connect, read/write values, adjust settings
`services`	Attribute, Configuration, Connection, Convenience, Discovery, Method, MonitoredItem, Node Management, Subscription, View	Full OPC UA Part 4 client workflows without PKI/PubSub/packet capture
`administration`	Configuration, Connection, NodeSet Export, PKI Management	Certificate trust management and NodeSet export
`pubsub`	PubSub runtime, discovery, action, and capture tools (plus PubSub decode when diagnostics tools are enabled)	Part 14 PubSub publish/subscribe, discovery, and capture workflows
`diagnostics`	Connection, Packet Capture (plus decode/replay when diagnostics tools are enabled)	OPC UA-aware packet capture, offline decode, and replay
`full` (default)	Every tool class above	Unrestricted access; the current-major default so existing integrations keep working unchanged

full is the default for the current major version — core and the other bounded profiles are opt-in. Select a profile with:

The --profile CLI option, e.g. opcua-mcp --profile core
The McpServer:ToolProfile configuration value
The OPCUA_MCP_TOOL_PROFILE environment variable

Because the exact number of tools in each profile (and in full) changes as tools are added or removed, this document intentionally does not hard-code a tool count. Use the tables above (or tools/list) to enumerate the tools actually exposed by a running server.

Resources

The MCP server exposes connected sessions as MCP resources, enabling the LLM to discover, inspect, and subscribe to session state.

Resource URI	Type	Description
`opcua://sessions`	Direct	List all active sessions with connection status
`opcua://sessions/{name}`	Template	Full details of a named session (endpoint, security, namespaces)
`opcua://sessions/{name}/namespaces`	Template	Server namespace table for a session

Multi-Session Support

The server supports multiple simultaneous sessions to different OPC UA servers. Each session is identified by a name.

Tool: Connect
  endpointUrl: "opc.tcp://server1:62541/ReferenceServer"
  name: "refserver"          (optional — auto-generated from hostname if omitted)
  autoAcceptCerts: true

Tool: Connect
  endpointUrl: "opc.tcp://plc1:4840"
  name: "plc1"

Tool: Browse
  nodeId: "i=85"
  sessionName: "refserver"   (optional — uses the only session if there's just one)

Tool: ReadValue
  nodeId: "ns=2;s=Temperature"
  sessionName: "plc1"

Sessions are listed via resources/list and detailed via resources/read.

Installation

Option 1: Install as a .NET global tool (recommended)

dotnet tool install --global OPCFoundation.NetStandard.Opc.Ua.Mcp

After installation, the opcua-mcp command is available globally.

Option 2: Run from source

cd tools/Opc.Ua.Mcp
dotnet run -c Release

Option 3: Install from local build

dotnet pack tools/Opc.Ua.Mcp/Opc.Ua.Mcp.csproj -c Release
dotnet tool install --global --add-source tools/Opc.Ua.Mcp/bin/Release OPCFoundation.NetStandard.Opc.Ua.Mcp

Configuration

Claude Desktop

Add to your claude_desktop_config.json (typically at %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "opcua": {
      "command": "opcua-mcp"
    }
  }
}

VS Code / GitHub Copilot

Add to your workspace .vscode/mcp.json:

{
  "servers": {
    "opcua": {
      "command": "opcua-mcp"
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "opcua": {
      "command": "opcua-mcp"
    }
  }
}

HTTP Transport (for remote clients)

By default, the server uses stdio transport for local tool integration. For remote clients, use the Streamable HTTP transport, exposed only at the /mcp path (there is no root route):

opcua-mcp --transport http --port 5100

The server listens at http://localhost:5100/mcp. --transport sse is a deprecated alias for http kept for the current major version only — prefer http in new configurations.

Usage

Typical Workflow

1. Discover endpoints (no session required):

Tool: GetEndpoints
  endpointUrl: "opc.tcp://localhost:62541/Quickstarts/ReferenceServer"

2. Connect to an OPC UA server (auto-select most secure, anonymous):

Tool: Connect
  endpointUrl: "opc.tcp://localhost:62541/Quickstarts/ReferenceServer"
  autoAcceptCerts: true

Or connect with specific security and authentication:

Tool: Connect
  endpointUrl: "opc.tcp://localhost:62541/Quickstarts/ReferenceServer"
  securityMode: "SignAndEncrypt"
  securityPolicy: "Basic256Sha256"
  authType: "Username"
  username: "admin"
  password: "password"
  autoAcceptCerts: true

2. Explore the address space:

Tool: BrowseAll
  nodeId: "i=85"     (Objects folder)
  maxDepth: 2
  maxResults: 50

3. Read values:

Tool: ReadValue
  nodeId: "ns=2;s=MyTemperatureSensor"

4. Write values:

Tool: WriteValue
  nodeId: "ns=2;s=MySetpoint"
  value: "72.5"
  dataType: "Double"

5. Call a method:

Tool: CallMethod
  objectId: "ns=2;s=MyMachine"
  methodId: "ns=2;s=StartProcess"
  inputArguments: ["fast", "true"]

6. Monitor changes:

Tool: CreateSubscription
  publishingInterval: 1000

Tool: CreateMonitoredItems
  subscriptionId: <from above>
  nodeIds: ["ns=2;s=Temperature", "ns=2;s=Pressure"]

Tool: Publish
  (retrieves queued notifications)

7. Manage PKI (trust rejected certificates):

Tool: ListCertificates
  store: "Rejected"

Tool: TrustCertificate
  thumbprint: "A1B2C3..."    (from ListCertificates results)

Tool: GetPkiStorePaths
  (shows where certificate stores are located on disk)

8. Adjust configuration for current session:

Tool: GetConfiguration
  (view current settings)

Tool: SetConfiguration
  operationTimeout: 60000
  maxArrayLength: 131072
  autoAcceptUntrustedCertificates: true

9. Export the server's address space to NodeSet2 XML:

Tool: ExportNodeSet
  filePath: "C:\\export\\server-nodeset.xml"
  startingNodeId: "i=85"     (Objects folder)
  exportMode: "Complete"     (includes values)

Or export split by namespace (one file per companion spec):

Tool: ExportNodeSetPerNamespace
  outputDirectory: "C:\\export\\namespaces"

10. Disconnect:

Tool: Disconnect

NodeId Formats

The MCP server accepts NodeIds in standard OPC UA string format:

Format	Example	Description
Numeric	`i=2258`	Numeric identifier in namespace 0
Numeric with namespace	`ns=2;i=1001`	Numeric identifier in namespace 2
String	`ns=2;s=MyVariable`	String identifier
GUID	`ns=2;g=12345678-1234-1234-1234-123456789abc`	GUID identifier
Opaque	`ns=2;b=Base64EncodedData`	ByteString identifier

Common Well-Known NodeIds

NodeId	Description
`i=84`	Root node
`i=85`	Objects folder
`i=86`	Types folder
`i=87`	Views folder
`i=2253`	Server object
`i=2258`	Server/ServerStatus/CurrentTime

Error Handling

When an OPC UA service returns an error, tools return a structured JSON response:

{
  "error": true,
  "statusCode": "BadNodeIdUnknown",
  "message": "The node id refers to a node that does not exist in the server address space."
}

This is normal behavior — not all servers support all services. Common status codes:

Status Code	Meaning
`BadServiceUnsupported`	Server doesn't implement this service
`BadNodeIdUnknown`	NodeId doesn't exist
`BadNotWritable`	Node attribute is read-only
`BadMethodInvalid`	Method not found on the specified object
`BadUserAccessDenied`	Insufficient permissions

PubSub Tools

In addition to the client services above, the server exposes OPC UA PubSub (Part 14) tools, backed by Opc.Ua.PubSub and Opc.Ua.PubSub.Diagnostics. See Diagnostics.md §5 for the capture / dissection details.

Configuration and Security Key Service methods. PubSub configuration (AddConnection, AddWriterGroup, AddReaderGroup, AddDataSetWriter, AddDataSetReader, Status.Enable / Disable) and the Security Key Service (GetSecurityKeys, AddSecurityGroup / RemoveSecurityGroup) are standard server-side PublishSubscribe object methods, so they are invoked with the generic Call tool rather than dedicated wrappers — pass the PublishSubscribe object NodeId (or the target connection / group NodeId) and the corresponding method NodeId (e.g. i=14443 for PublishSubscribe_AddConnection, i=15215 for PublishSubscribe_GetSecurityKeys).

In-process publish/subscribe runtime:

Tool	Purpose
`pubsub_runtime_start_publisher` / `pubsub_runtime_start_subscriber`	Start an in-process UDP publisher / subscriber
`pubsub_runtime_publish`	Publish a DataSet update
`pubsub_runtime_read_received`	Read DataSets received by the subscriber
`pubsub_runtime_status` / `pubsub_runtime_stop`	Status / stop the runtime

Discovery (Part 14 §7.2.4.6 — send a discovery request from the active runtime and collect publisher responses):

Tool	Purpose
`pubsub_discover_metadata`	Learn the field-level schema of a DataSetWriter (names, field count)
`pubsub_discover_writer_config`	Learn a publisher's WriterGroupId and DataSetWriterIds
`pubsub_discover_publisher_endpoints`	Learn a publisher's transport endpoint URLs

Actions (Part 14 §7.2.5.6 — request/response over PubSub):

Tool	Purpose
`pubsub_invoke_action`	Invoke an action target and await the correlated response
`pubsub_register_action_responder`	Register a demo/echo responder for round-trip testing
`pubsub_bind_action_method`	Bind an action to a server method (ObjectId/MethodId)
`pubsub_list_action_targets` / `pubsub_list_action_responders`	List known targets / registered responders

Capture and dissection:

Tool	Purpose
`pubsub_start_capture` / `pubsub_stop_capture` / `pubsub_capture_status`	Manage an in-process PubSub capture session
`pubsub_write_pcap`	Flush captured frames to `.pcap` / `.pcapng`
`pubsub_dissect_capture`	Dissect captured frames (decrypts encrypted UADP when a key log is supplied)
`pubsub_decode_pcap`	Decode a libpcap file of UDP PubSub traffic
`pubsub_load_keylog`	Load a PubSub key log for offline decryption

Architecture

The MCP tools ship as four libraries plus the executable that composes them. The executable owns only transport, logging and CLI plumbing; every tool lives in a library that an application can reference on its own.

tools/
├── Opc.Ua.Mcp.Core/                     # Part 4 service tools, session manager, options, filters
│   ├── OpcUaMcpCoreExtensions.cs        # AddOpcUaMcpCore, WithOpcUaCoreTools, WithOpcUaMcpFilters
│   ├── OpcUaSessionManager.cs           # OPC UA client session lifecycle
│   ├── McpCapturePath.cs                # Path-traversal guard shared by the capture packages
│   ├── Tools/
│   │   ├── ConnectionTools.cs           # GetEndpoints, Connect, Disconnect, GetConnectionStatus
│   │   ├── AttributeServiceTools.cs     # Read, Write, HistoryRead, HistoryUpdate
│   │   ├── ViewServiceTools.cs          # Browse, BrowseNext, TranslateBrowsePaths, etc.
│   │   ├── NodeManagementServiceTools.cs# AddNodes, AddReferences, DeleteNodes, etc.
│   │   ├── MethodServiceTools.cs        # Call
│   │   ├── SubscriptionServiceTools.cs  # CreateSubscription, Publish, etc.
│   │   ├── MonitoredItemServiceTools.cs # CreateMonitoredItems, etc.
│   │   ├── DiscoveryServiceTools.cs     # FindServers, RegisterServer, etc.
│   │   ├── PkiTools.cs                  # ListCertificates, TrustCertificate, etc.
│   │   ├── ConfigurationTools.cs        # Full-profile compatibility configuration tools
│   │   ├── ConfigurationReadTools.cs    # Profile-safe configuration reader
│   │   ├── ConfigurationUpdateTools.cs  # Focused transport/client/security setters
│   │   ├── NodeSetExportTools.cs        # ExportNodeSet, ExportNodeSetPerNamespace
│   │   └── ConvenienceTools.cs          # ReadValue, BrowseAll, CallMethod, etc.
│   └── Serialization/
│       └── OpcUaJsonHelper.cs           # OPC UA ↔ JSON type conversion
├── Opc.Ua.Mcp.PubSub/                   # PubSub runtime, actions and discovery
│   ├── PubSubRuntimeManager.cs
│   └── Tools/{PubSubRuntime,PubSubAction,PubSubDiscovery}Tools.cs
├── Opc.Ua.Mcp.Diagnostics/              # UA-TCP capture, decode and replay
│   └── Tools/{PacketCapture,PacketDecode,PacketReplay}Tools.cs
├── Opc.Ua.Mcp.PubSub.Diagnostics/       # PubSub capture and decode
│   └── Tools/{PubSubCapture,PubSubDecode}Tools.cs
└── Opc.Ua.Mcp/                          # .NET 10 project, packaged as dotnet tool
    ├── Program.cs                       # Entry point, stdio + Streamable HTTP transport (/mcp)
    ├── McpHostBuilder.cs                # Composes the four libraries
    ├── Opc.Ua.Mcp.Config.xml            # OPC UA client application config
    └── .mcp/server.json                 # MCP server manifest for NuGet discovery

Packages

Package	Tools	Depends on
`OPCFoundation.NetStandard.Opc.Ua.Mcp.Core`	Part 4 services, connection, configuration, PKI, NodeSet export	`Opc.Ua.Core`, `.Configuration`, `.Client`
`OPCFoundation.NetStandard.Opc.Ua.Mcp.PubSub`	PubSub runtime, actions, discovery	Core + `Opc.Ua.PubSub`
`OPCFoundation.NetStandard.Opc.Ua.Mcp.Diagnostics`	UA-TCP capture, decode, replay	Core + `Opc.Ua.Core.Diagnostics`
`OPCFoundation.NetStandard.Opc.Ua.Mcp.PubSub.Diagnostics`	PubSub capture, decode	Core + `Opc.Ua.PubSub.Diagnostics`
`OPCFoundation.NetStandard.Opc.Ua.Mcp`	the ready-to-run `opcua-mcp` tool	all of the above

The libraries multi-target net8.0;net9.0;net10.0; the executable targets net10.0.

Embedding the tools in your own MCP server

An application that wants OPC UA tools and its own application-level tools composes them rather than shelling out to opcua-mcp:

using Microsoft.Extensions.DependencyInjection;
using Opc.Ua.Mcp;

builder.Services.AddOpcUaMcpCore();

builder.Services.AddMcpServer()
    .WithStdioServerTransport()
    .WithOpcUaMcpFilters()
    .WithOpcUaCoreTools(McpToolProfile.Services)
    .WithTools<MyApplicationTools>();

Add any of the other packages the same way — each contributes a service registration and a tool registration:

builder.Services.AddOpcUaMcpPubSub();
builder.Services.AddOpcUaMcpDiagnostics();
builder.Services.AddOpcUaMcpPubSubDiagnostics();

mcp.WithOpcUaPubSubTools(profile)
   .WithOpcUaDiagnosticsTools(profile, diagnosticsEnabled)
   .WithOpcUaPubSubDiagnosticsTools(profile, diagnosticsEnabled);

WithOpcUaMcpFilters registers the request and schema filters that make tool errors actionable and tool schemas explicit. Call it once per server, even when several OPC UA tool packages are composed.

McpToolProfile is shared vocabulary that lives in Core, and each package maps the profile to its own tools. A profile a package does not own contributes nothing rather than failing, so the same profile value can be passed to every package a host references — Full in a host that never referenced Opc.Ua.Mcp.Diagnostics simply yields no capture tools.

The capture tool classes stay internal and are reachable only through their registration extensions.

Security Notes

The autoAcceptCerts parameter is for testing only. In production, configure proper certificate trust using the OPC UA certificate stores under %LocalApplicationData%/OPC Foundation/pki/.
The server manages a single OPC UA session at a time. Disconnect before connecting to a different server.
Application certificates are automatically created on first use and stored in the local certificate store.
Logs are written to %LocalApplicationData%/OPC Foundation/Logs/McpServer.log.txt.

Agent-Usability Quality Gate

Contributors can run the same deterministic static and live-probe grading used in CI:

./tools/Opc.Ua.Mcp/Test-McpGrade.ps1

The script builds the server, checks out mcpgrade at the reviewed commit pinned in the script, grades the core and full Streamable HTTP catalogs, and probes the full stdio catalog. Reports are written under artifacts/mcpgrade by default.

The repository .mcpgraderc.json disables N002 after descriptions have been disambiguated. RegisterServer/RegisterServer2 are OPC UA standard service names, while ReadValue/ReadValues and GetConfiguration/SetConfiguration are compatibility-sensitive singular/plural and get/set pairs. These names must not be changed solely to satisfy edit-distance heuristics.

Requirements

.NET 10 SDK or later
An OPC UA server to connect to