OPC UA MCP Server

🏭 OPC UA MCP Server

Let Claude, Codex, Gemini and any other MCP agent read sensors, browse the plant and — only when you allow it — control equipment on any OPC UA server.

[▶ Try it without hardware](#try-it-without-a-plant) — a simulated plant ships in this repository

Quick start · Connect your agent · Tools · Production · Docs · Contributing

Official MCP Registry · Glama · HardwareMCP

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"].

Claude Desktop

Easiest — the bundle. Download opcua-mcp-server- .mcpb from the latest release, drag it into Settings → Extensions, and fill in OPC UA endpoint. No Node, no Python, no JSON.

Or let the server write the config (needs Node or Python):

npm install -g opcua-mcp-server      # or: uv tool install opcua-mcp-server

opcua-mcp-server --install claude-desktop --url opc.tcp://localhost:4840/freeopcua/server/ --dry-run

It checks the config with the server's own startup validation and writes absolute paths, because Claude Desktop does not inherit your shell's PATH. The profile defaults to read-only; encryption, a pinned server certificate, a control profile, a policy file and an audit file are all flags, and passwords are never taken as flags. Check the preview, then repeat the command without --dry-run to write the configuration and restart Claude Desktop. Every flag and safety rule, editing claude_desktop_config.json by hand, and fixing a server that fails to start: docs/install.md.

Claude Code

claude mcp add opcua -e OPCUA_SERVER_URL=opc.tcp://localhost:4840/freeopcua/server/ -- npx -y opcua-mcp-server

Add --scope project to share it with your team through .mcp.json.

OpenAI Codex

codex mcp add opcua --env OPCUA_SERVER_URL=opc.tcp://localhost:4840/freeopcua/server/ -- npx -y opcua-mcp-server

Or add it to ~/.codex/config.toml:

[mcp_servers.opcua]

command = "npx" args = ["-y", "opcua-mcp-server"] env = { OPCUA_SERVER_URL = "opc.tcp://localhost:4840/freeopcua/server/" }

Or let the server write that entry, with the same checks as for Claude Desktop: opcua-mcp-server --install codex --url opc.tcp://localhost:4840/freeopcua/server/ --dry-run. This installer command requires a permanent package installation first: npm install -g opcua-mcp-server or uv tool install opcua-mcp-server. Check the preview and repeat without --dry-run to write it.

Gemini CLI

Add to ~/.gemini/settings.json, or .gemini/settings.json in a project:

{

"mcpServers": { "opcua": { "command": "npx", "args": ["-y", "opcua-mcp-server"], "env": { "OPCUA_SERVER_URL": "opc.tcp://localhost:4840/freeopcua/server/" } } } }

Google Antigravity

In the agent panel, open ⋯ → MCP Servers → Manage MCP Servers → View raw config, add the entry below to mcp_config.json, and restart Antigravity:

{

"mcpServers": { "opcua": { "command": "npx", "args": ["-y", "opcua-mcp-server"], "env": { "OPCUA_SERVER_URL": "opc.tcp://localhost:4840/freeopcua/server/" } } } }

Cursor

Add to ~/.cursor/mcp.json, or .cursor/mcp.json in a project:

{

"mcpServers": { "opcua": { "command": "npx", "args": ["-y", "opcua-mcp-server"], "env": { "OPCUA_SERVER_URL": "opc.tcp://localhost:4840/freeopcua/server/" } } } }

VS Code (GitHub Copilot)

Add to .vscode/mcp.json — note the top-level key is servers:

`