OPC UA MCP Server

What OPC-UA MCP Server MCP server does

OPC-UA MCP Server MCP server gives an MCP client access to an OPC-UA server's address space and live values. Agents can read one or more nodes, write values after type validation, inspect node metadata, browse child nodes, and recursively explore the hierarchy. Name-based lookup and fuzzy matching are available through a background discovery process and its search index.

The server also supports push subscriptions. An agent can subscribe to one or more nodes at a selected interval, list active subscriptions, or cancel them by subscription ID or node. Subscriptions are persisted and re-established after reconnects. MCP resources expose individual nodes through opcua://node/{node_id} and expose server information through opcua://server.

How it works

The process communicates with MCP clients through stdio by default or through HTTP when SERVER_TRANSPORT=http is selected. In stdio mode, the OPC-UA connection is opened when the client invokes opcua_connect; HTTP mode connects during startup. opcua_disconnect provides explicit connection control where needed.

Read-through caching stores read results, browse results, and type information on disk using bbolt. Cached values can reduce repeated device requests, and writes invalidate affected cache entries. Subscribed values are served from the live cache. Discovery periodically crawls the configured address-space root, then stores browse names in a Bleve index for partial and fuzzy searches.

Setup and configuration

Build the executable with Go 1.26 or newer:

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

Set OPCUA_ENDPOINT to point at an OPC-UA server; the default is opc.tcp://localhost:4840. For HTTP transport, set SERVER_TRANSPORT=http; the default HTTP port is 8080 and the MCP path is /mcp. Docker is optional and can be used with the repository's bundled test-server deployment.

Configuration may come from an optional YAML, TOML, JSON, or other Viper-supported file. Environment variables take precedence. Authentication supports anonymous access, username and password, or a client certificate. Security policy, security mode, request and session timeouts, retry behavior, discovery depth, search limits, cache settings, and the bbolt database path are configurable.

Tools and capabilities

Core tools include opcua_read, opcua_write, opcua_get_value, opcua_get_value_by_name, opcua_browse, opcua_browse_nodes, and opcua_node_info. Search and discovery tools include opcua_find_similar_nodes, opcua_discovery_stats, and opcua_force_discovery. Subscription tools manage updates with opcua_subscribe, opcua_unsubscribe, and opcua_list_subscriptions.

opcua_server_info reports server metadata. opcua_debug_search and opcua_ensure_server_nodes help investigate discovery and search issues. The OPC-UA MCP Server MCP server validates write types before sending values to the device.

Limitations and notes

The server depends on the target OPC-UA endpoint and its configured authentication and security settings. Discovery and search depend on the configured crawl root, depth, node limits, and enabled flags. The on-disk store must be writable when caching and subscription persistence are needed.

If the bbolt store cannot open, the server continues with caching disabled, while subscription tools return errors; other tools remain available. In stdio mode, logs are forced to stderr when the configured output would otherwise use stdout, because stdout carries the MCP protocol stream.