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.git
cd opcua-mcp
make compose-up        # starts a test OPC-UA server, opcua-mcp, and a public HTTPS tunnel
make 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 startup
SERVER_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

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 Docker
make run-with-test-server    # run the app against it (auto start/stop)

go test ./...                # unit tests
go 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.

Contributing

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

License

MIT