industriagents/opcua-mcp

Every tool call and value above is a real response from the bundled simulator, recorded through the Python bridge under the read-only observe profile; the question and answer text are scripted. Rebuild it with scripts/readme_demo.py.

This project is a bridge between an AI agent and an OPC UA server. OPC UA is the protocol used to expose industrial equipment and its data; MCP (Model Context Protocol) lets an agent call tools to work with that data. The bridge runs on your computer and connects to an existing OPC UA server, or to a local simulator for a first test.

Your MCP client starts the bridge as a local stdio process: it exchanges MCP messages over standard input and output. One process connects one client context to one OPC UA endpoint. Use a separate process for each endpoint. Remote MCP and shared multi-client operation are gated by the identity and isolation RFC.

Features

• 🔌 Any OPC UA server — PLC, SCADA gateway or historian. Nothing to install on the plant side.
• 🧰 The whole operator toolkit — read, browse, history and aggregates, subscriptions, events and alarms, writes and method calls.
• 🛡️ Read-only by default — writes and method calls need an explicit control profile and an authenticated server (pinned certificate or CA trust store). The operator profile also requires allowlisted targets, and every control call is audited.
• 🐍 Python or Node — two first-class runtimes with the same tool contract. Use whichever you have, accounting for the documented runtime differences.
• 📦 One-file Claude Desktop install — a .mcpb bundle with nothing else to set up.

flowchart LR
    A["AI agent(Claude, Codex, Gemini, Cursor…)"] -->|MCP over stdio| B["OPC UA MCP Server(Python or Node)"]
    B -->|OPC UA| C["OPC UA server(PLC / SCADA / historian)"]

Quick start

Follow these steps in order: choose an installation, start or identify an OPC UA server, configure your MCP client, then check the connection. You need an MCP client such as one of the agents listed below.

1. Choose an installation

Choose one runtime; you do not need both. The package routes fetch the server on demand, so you do not need to clone this repository to use an existing OPC UA server.

For a package route, check that it can run from your terminal. Run the command for your chosen runtime:

# Node
npx -y opcua-mcp-server --version

# Or Python
uvx opcua-mcp-server --version

These commands print a version and exit. In normal use, your MCP client launches the server without --version; you do not also start the bridge in a separate terminal. A bridge started by itself waits for MCP messages, rather than showing an interactive prompt or a web page.

2. Choose an OPC UA endpoint

For an existing server, get its endpoint URL, including any path, from its administrator (for example opc.tcp://192.168.0.10:4840). The bridge reads it from OPCUA_SERVER_URL, which you set in your MCP client’s configuration in step 3. If unset, the default is opc.tcp://localhost:4840.

The default profile is observe (read-only), and the default OPC UA connection is unencrypted and anonymous. Use those defaults for the local mock. For real equipment, prepare the security configuration before connecting.

Try it without a plant

If you do not have an OPC UA server, start the bundled simulated plant. This optional route needs Git, Python 3.10+ and uv, even if you chose the Node bridge. Run these commands in a terminal:

git clone https://github.com/IndustriAgents/OPCUA-MCP.git
cd OPCUA-MCP
uv sync --all-packages
uv run --no-sync opcua-mock-server

Wait for Server is running and ready for connections, then leave this terminal running. The mock listens on port 4840; use opc.tcp://localhost:4840/freeopcua/server/ as your endpoint. Stop it with Ctrl-C when finished. If the port is busy, choose another port with uv run --no-sync opcua-mock-server --endpoint opc.tcp://127.0.0.1:14840/freeopcua/server/ and use that URL in your client configuration.

The plant supports browsing, sensor reads, data-change subscriptions, raw value history, plain events and event history. It also has writable actuators and methods, subject to the bridge’s control policy. It does not implement processed aggregates or Alarms & Conditions: its plain alarm events cannot be listed as retained conditions, acknowledged or acted on with alarm-action tools. Use the separate mocks for those operations:

The separate mocks need Node and npm; their READMEs give installation and startup commands. The MCP Inspector walkthrough has more examples, and the compatibility matrix records tested coverage.

Connect your agent

3. Configure the client and launch the bridge

Pick one client below. The examples use the local plant endpoint from step 2; replace opc.tcp://localhost:4840/freeopcua/server/ with your endpoint if needed. For a secure connection, add the settings from Going to production to the same env block (or the bundle’s settings fields).

To use Python in a JSON configuration, set "command": "uvx" and "args": ["opcua-mcp-server"]. In a CLI registration command, replace npx -y opcua-mcp-server with uvx opcua-mcp-server. In TOML, use command = "uvx" and args = ["opcua-mcp-server"].

[!TIP] No Node or Python on the machine? Download a single-file executable from the latest release and use its path as the command — see docs/install.md. Several PLCs? Each entry talks to one endpoint, so add one entry per PLC (why).

4. Check the connection

Restart your desktop client or start a new CLI client session after configuring it, then enable or approve the opcua server if your client asks. The client starts the bridge automatically.

Ask: “Use get_server_status to check the OPC UA connection.” A working connection reports connected: true. Then ask: “Browse the OPC UA variables and read the current temperature.” Against the plant mock, this works with the default read-only profile.

If it fails, check that the OPC UA server is still running and that OPCUA_SERVER_URL matches its endpoint. If the bridge cannot launch, check its logs and the client command’s path; desktop clients may need absolute paths. The installation guide explains client command paths, and testing troubleshooting covers startup, connection and tool errors.

What you can ask

• “Show me all the variables in the system.”
• “What was the temperature over the last hour? Give me the hourly average.”
• “Watch the tank level and tell me what it does over the next minute.”
• “What alarms are active right now?”
• “Set the valve position to 80%.” — needs the operator profile
• “Start production on line 1 at 100 units/hour.” — needs the operator profile

These prompts depend on the connected server’s nodes and capabilities. Server-computed averages need processed aggregate support, and active alarms need Alarms & Conditions; see the mock coverage above. Writes and method calls also need allowlisted targets and the security settings below, in addition to the operator profile.

Every reading comes back with its data type, status, timestamps and engineering units — never a bare number. What a result looks like.

Tools

15 tools, identical on both runtimes and defined once in contract/tools.json. Arguments, results and limits: docs/tools.md.

Control and alarm tools also need a verified server (a secured channel and a pinned OPCUA_SERVER_CERT or an OPCUA_SERVER_TRUST_STORE) unless a lab override is set. † Works only on a server that advertises the feature it needs, such as historical access.

Going to production

[!WARNING] Out of the box the agent can only read, but the OPC UA channel is unencrypted and anonymous — fine for the mock or a lab, not for real equipment. Secure the channel before connecting to anything that matters.

1. Secure the channel and pin the server — add these settings to your MCP client’s env block, using paths to your actual certificate files. The following blocks show environment names and values; in JSON, enter them as quoted key/value pairs. Generate certificates and arrange trust with the OPC UA administrator as described in docs/certificates.md.

OPCUA_SECURITY_POLICY=Basic256Sha256     # implies SignAndEncrypt
OPCUA_CLIENT_CERT=/etc/opcua/client.pem  # this client's identity
OPCUA_CLIENT_KEY=/etc/opcua/client_key.pem
OPCUA_SERVER_CERT=/etc/opcua/server.pem  # pin the server you meant to reach

Choose one user authentication method alongside those channel settings. For username/password authentication, provide both:

OPCUA_USERNAME=mcp-operator
OPCUA_PASSWORD=

Supply the real password through your client’s secret storage or environment; the installer never accepts a password flag. See password handling for client-specific setup.

Alternatively, for X.509 user authentication, leave OPCUA_USERNAME and OPCUA_PASSWORD unset and provide both of these instead:

OPCUA_USER_CERT=/etc/opcua/user.pem
OPCUA_USER_KEY=/etc/opcua/user_key.pem

The user certificate and key identify the user; they are separate from OPCUA_CLIENT_CERT and OPCUA_CLIENT_KEY, which secure the channel. Keep the channel settings in either case: X.509 user authentication requires a security policy other than None.

Instead of pinning with OPCUA_SERVER_CERT, you can use OPCUA_SERVER_TRUST_STORE together with OPCUA_SERVER_APPLICATION_URI for CA trust-store verification; see the certificate guide.

2. Decide what the agent may do with OPCUA_PROFILE:

3. Keep a record — set OPCUA_AUDIT_FILE for an append-only log of every control call.

Misconfiguration stops the server at startup with a message naming the variable, rather than failing later against live equipment. The MCP policy is defence in depth, not a replacement for OPC UA authorisation: scope the OPC UA account to the same nodes and methods.

Every setting, value bounds on writes and allowlists that survive a server restart: docs/configuration.md. Threat model: SECURITY.md. Certificates: docs/certificates.md.

Documentation

Contributing

Contributions are welcome — see CONTRIBUTING.md for the project layout, local development and adding a tool to both runtimes.

New here? The good first issues are small and scoped to one pull request: a setup guide for another MCP client, or a sample application built on the simulated plant. None needs OPC UA hardware.

The most useful thing you can send is a result from a real OPC UA server: open a compatibility report saying which server, which version and which tools worked. Test only on equipment you are authorised to use, and keep writes and method calls to a simulator or lab.

License

MIT — see LICENSE.

Tool inputs and structured results use JSON Schema draft 2020-12 with generated TypeScript/Python types and CI drift checks. See contract generation for the authoring workflow.