OPC-UA MCP Server

OPC-UA MCP Server

An MCP server that lets an LLM read, write, browse, search, and subscribe to live data on an OPC-UA industrial automation server - over stdio or HTTP, with a persistent cache and a searchable index of the address space built in.

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

Quick start

The fastest way to see it working end-to-end, using the bundled Microsoft OPC-UA test server and a public tunnel Claude can reach:

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

Paste that URL into Claude at Settings → Connectors → Add custom connector, then ask it to browse the server or read a value. Stop with make compose-down when you're done - see docs/deployment.md for what that tunnel exposes and how to run against your own OPC-UA server instead.

Building and running locally

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 startupSERVER_TRANSPORT=http OPCUA_ENDPOINT=opc.tcp://localhost:4840 ./opcua-mcp

Requires Go 1.26+ and, optionally, Docker for the test server / containerized deployment.

What it does

• Read / write node values, with type validation on writes so a mismatched value is rejected before it reaches the device.
• Browse the address space one level at a time or recursively, and look nodes up by name instead of by node ID.
• Subscribe to push-based live updates - subscriptions persist across restarts and are automatically re-established on reconnect.
• Cache reads, browse results, and type info on disk (bbolt), so repeat lookups don't round-trip to the device; writes invalidate the relevant entry automatically.
• Discover and search the address space in the background, indexed with Bleve for fuzzy/partial browse-name lookups.
• Anonymous, username/password, or certificate auth, with configurable OPC-UA security policy and mode.

See docs/architecture.md for how the caching layer, subscription manager, and discovery index fit together.

MCP tools

Read-only mode

Set MCP_READ_ONLY=true to expose only tools that don't change anything on the OPC-UA server or the connection: opcua_write, opcua_disconnect, opcua_subscribe and opcua_unsubscribe are hidden from tools/list, and a client that calls one of them by name gets an error instead of running it. opcua_connect and the discovery tools stay available.

To approve specific tools on top of the read-only set, list them in MCP_ALLOWED_TOOLS, for example MCP_ALLOWED_TOOLS=opcua_subscribe,opcua_unsubscribe. An unknown tool name stops the server at startup, so a typo can't silently leave a tool disabled. Any tool added in a future release is excluded from read-only mode until it is classified as read-only.

MCP resources

Configuration

Configuration is loaded (via viper) from three sources, in ascending order of precedence:

1. Built-in defaults (shown in the tables below).
2. An optional config file - TOML, YAML, JSON, or any other format viper supports. By default ./config.{yaml,yml,toml,json,...} is read if present; point at an explicit path with CONFIG_FILE=/path/to/config.toml. A config file is entirely optional - env vars alone are still enough.
3. Environment variables (SERVER_*, OPCUA_*, MCP_*, SEARCH_*, STORE_*) - always win over the config file, so existing env-var-only deployments keep working unchanged.

A config file mirrors the env var names, lowercased and nested under each prefix, e.g. SERVER_HTTP_PORT becomes:

server:  http_port: "8080"

Server

OPC-UA connection

MCP

Discovery and search

Persistent store

Backs read-through caching and subscription persistence with an on-disk bbolt database.

If the store fails to open (e.g. a stale lock from a prior ungraceful shutdown, or a read-only filesystem), the server logs a warning and keeps running with caching forced off and subscription tools returning an error - every other tool is unaffected.

Telemetry

opcua-mcp collects anonymous, aggregate usage telemetry (which tools get used, cache hit rate, error categories - never node IDs, endpoint URLs, node values, or credentials) to help prioritize maintenance of this open-source project. It's on by default; see docs/telemetry.md for exactly what is and isn't collected.

Opt out with either:

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

Multi-stage build on Chainguard's minimal Go image, running from scratch - no shell, small attack surface. Mount ./search_index and ./mcp_opcua_store.db as volumes to persist discovery/cache/subscription state across restarts. Full auth-mode examples, the Compose dev stack, and the Claude-connector tunnel setup are in docs/deployment.md.

Development

make start-opcua-server      # Microsoft OPC-UA test server in Dockermake run-with-test-server    # run the app against it (auto start/stop)
go test ./...                # unit testsgo test -race ./...make test-integration        # real Subscribe/reconnect/cache behavior via testcontainers-go (needs Docker)

VS Code launch configs are in .vscode/launch.example.json - copy to .vscode/launch.json to get stdio/HTTP/auth debug targets that start and stop the test server automatically. make help lists every available target.

Tests are table-driven and mock the OPC-UA client at the opcuaClient interface seam (internal/opcua/mock_client_test.go) rather than against a live/simulated server - see docs/architecture.md for how the pieces being tested fit together, and docs/COMMIT_CONVENTION.md for this repo's commit message format.

Changelog

Unreleased

• New: read-only mode. MCP_READ_ONLY=true hides and rejects opcua_write, opcua_disconnect, opcua_subscribe and opcua_unsubscribe; MCP_ALLOWED_TOOLS re-enables named tools. Off by default, so existing setups see all 18 tools as before.
• New: automatic recovery from a dead OPC-UA session. When the server rejects a request with BadSessionIDInvalid or BadServerNotConnected (for example after the server restarted or dropped the session), the client reconnects once with the same security settings and retries reads once. Writes are not replayed: they return an error saying the write was not applied, and the next call uses the new session. Subscriptions are restored after the reconnect.
• Changed: opcua_connect verifies the connection. When already connected it now probes the server and rebuilds the session if it is no longer usable, instead of only reporting "Already connected".
• Fixed: opcua_disconnect stays disconnected. Disconnecting no longer makes the subscription reconnect watcher bring the connection back.

Contributing

Fork it, make your changes, open a PR - see CONTRIBUTING.md.

License

MIT