graccess-mcp

A natural language interface for AVEVA System Platform, built on the Model Context Protocol (MCP). Enables operators, engineers and pre-sales teams to query and configure industrial automation systems using conversational AI with no data leaving the facility.

Disclaimer

This project is a proof of concept and is not intended for production use. It is developed and maintained by a single individual and is not officially supported by AVEVA. The project is provided "as is" without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and non-infringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

---

The Problem

AVEVA System Platform is a powerful industrial automation platform but, interacting with it requires navigating a proprietary IDE, understanding a domain-specific object model and knowing the exact location of configuration data across potentially thousands of objects. This creates friction for engineers doing routine configuration work and raises the barrier to entry for new users.

At the same time, AI assistants are transforming how knowledge workers interact with complex systems but most AI tooling assumes cloud connectivity, which is sometimes incompatible with the security requirements of operational technology (OT) environments.

---

The Solution

graccess-mcp bridges AVEVA System Platform and local large language models via the Model Context Protocol. It exposes galaxy configuration data as AI-callable tools, enabling natural language queries and operations against a live System Platform environment. Entirely on-premises, with no internet connection required.

A purpose-built browser chat UI connects to both the MCP server and a locally-running Ollama instance, giving users a clean conversational interface to the underlying automation system.

---

Key Capabilities

Capability	Description
Query	List all objects, templates, and instances in a galaxy
Inspect	Read attribute values from any object by name
Navigate	View the model, deployment, and derivation hierarchy
Configure	Write attribute values with full checkout/checkin lifecycle
Create	Instantiate new objects from templates via natural language
Deploy	Deploy instances to host engines, with automatic host assignment

Example interactions:

"What instances are in this galaxy?"
"What is the scan rate configured on AppEngine?"
"Create a new instance called Pump_042 from the TrainingObject template on host AppEngine"
"What attributes does $TrainingObject have?"
"Show me the full deployment view"
"Set the Description on Pump_042 to 'North cooling loop feed pump'"
"Deploy Pump_042"

---

Architecture

Browser Chat UI (Starlette/SSE)
        │
        ├── Ollama API ──► Local LLM (Ministral, Granite, etc.)
        │                   running in WSL on host machine
        └── MCP Client
                │
                ▼
        GRAccess MCP Server (FastMCP/SSE)
                │
                ▼
        GRAccess Python Wrapper
                │
                ▼
        ArchestrA GRAccess COM API
                │
                ▼
        AVEVA System Platform Galaxy

If the machine used for the PoC does not have a GPU, LLM inference will be very slow and will saturate the CPU. It is recommended to run the chat UI and the LLM model on a host with a discrete GPU. The MCP server must run on the same machine as the IDE/Galaxy. Example architecture:

[Host]                                [VM]
┌──────────────────────┐              ┌─────────────────────────┐
│ Browser :8080        │              │ GRAccess-MCP:8000       │
│ Chat UI Backend      │<──HTTP/SSE──>│  (config data, 32-bit)  │
│ Ollama :11434        │              │                         │
│                      │              │ OPCUA-MCP:8002          │
│                      │<──HTTP/SSE──>│  (live data, 64-bit)    │
│                      │              │            ↕            │
│                      │              │ System Platform         │
│                      │              │ OPC-UA Server :4840     │
└──────────────────────┘              └─────────────────────────┘

Design Decisions

Local-first, air-gapped by design. The LLM runs on-premises via Ollama. No queries, no configuration data and no credentials leave the network. This is a hard requirement for most OT/ICS environments and a key differentiator from cloud-based AI tooling.

MCP as the integration layer. The Model Context Protocol provides a standard interface between AI models and external tools. By implementing MCP, this project is compatible with any MCP-capable client. Claude Desktop, VS Code Copilot, custom UIs, or the included browser interface.

SSE transport over stdio. FastMCP's stdio transport uses Windows IOCP pipe handling, which interferes with COM apartment threading required by the GRAccess API. SSE transport uses TCP sockets and avoids this entirely.

Dedicated COM thread. All GRAccess COM calls run on a single-threaded executor with CoInitialize(). This isolates COM from Python's async event loop and prevents threading-related API failures.

Explicit checkout lifecycle. System Platform uses a checkout/checkin model to prevent concurrent edits. Every write operation (set attribute, create instance, deploy) fully manages this lifecycle. Checking out before modification, saving and checking in. The galaxy is left in a clean state compatible with concurrent IDE use.

---

Technology Stack

Component	Technology
MCP Server	Python, FastMCP
Chat UI Backend	Python, Starlette, SSE
Chat UI Frontend	Vanilla HTML/JS
LLM Runtime	Ollama (local, WSL)
SCADA Integration	AVEVA System Platform GRAccess COM API via pythonnet
Python Runtime	CPython 3.13 32-bit (required for 32-bit COM DLLs)

---

Project Structure

graccess-mcp/
  graccess/               Python wrapper around the GRAccess COM API
    client.py             GRAccessClient — connects to a System Platform node
    galaxy.py             Galaxy session — all query, read, and write operations
    exceptions.py         Domain exceptions
  mcp_server/
    server.py             FastMCP server — exposes graccess as MCP tools
  chat_ui/
    main.py               Starlette web backend
    ollama_loop.py        Ollama tool-calling loop with MCP integration
    mcp_client.py         MCP client — calls the MCP server over SSE
    static/index.html     Browser chat interface
  graccess-test/          Integration test and debug scripts
  lab/
    mcp_servers.json      MCP server config template
  start_mcp_server.ps1    MCP server start script
  chat_ui/start_chat_ui.ps1  Chat UI start script

---

Setup GRAccess MCP Server

Prerequisites

• AVEVA System Platform installed and running
• Python 3.13 32-bit (python.org)
• uv package manager

Install

# Install uv (Package Manager) much faster than pip
pip install uv

# MCP server environment (32-bit Python required)
uv venv .venv-grserver --python "C:\...\Python313-32\python.exe"
uv pip install -r requirements-server.txt --python .venv-grserver\Scripts\python.exe

Configure

Copy lab\mcp_servers.json to the project root as mcp_servers.json and fill in your environment:

{
  "mcpServers": {
    "GRAccess": {
      "command": "C:/Windows/py.exe",
      "args": ["-3.13-32", "C:/path/to/mcp_server/server.py"],
      "env": {
        "SYSTEMPLATFORM": "YOUR-HOSTNAME",
        "GRACCESS_GALAXY": "YOUR-GALAXY",
        "GRACCESS_USER": "DefaultUser",
        "GRACCESS_PASSWORD": "BLANK"
      }
    }
  }
}

Make the MCP Server listen on the network: Replace mcp = FastMCP("GRAccess") with mcp = FastMCP("GRAccess", host="0.0.0.0", port=8000) in

#Create firewall rule
New-NetFirewallRule -DisplayName "MCP Server SSE" -Direction Inbound -LocalPort 8000 -Protocol TCP -Action Allow

Run

# Terminal 1
.\start_mcp_server.ps1

The log should show INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

IMPORTANT: It must show IP address 0.0.0.0, so it is accessible from the network.

Setup Chat UI

Prerequisites

• Python 3.x 64-bit
• uv package manager
• Ollama with at least one model pulled

Install

# Install uv (Package Manager) much faster than pip
pip install uv

# Chat UI environment
uv venv .venv-grchat
uv pip install -r requirements-chat.txt --python .venv-grchat\Scripts\python.exe

# Install Ollama
irm https://ollama.com/install.ps1 | iex 

# Download at least one model with tool support: 
ollama pull granite4:latest

Update OLLAMA_URL in chat_ui/main.py to point to your Ollama instance, for example http://localhost:11434. Update MCP_URL in chat_ui/mcp_client.py to point to your MCP server, and set the default model to one of the downloaded models, for example granite4:latest.

# Terminal 2
.\chat_ui\start_chat_ui.ps1

The log should show INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

Open http://127.0.0.1:8080, select a galaxy and model, and start chatting.

---

MCP Tools

Tool	Description
list_galaxies	List all galaxies on the configured node
connect_galaxy	Select a galaxy to work with
disconnect_galaxy	Clear the galaxy selection
query_objects	List all instances or templates
get_attribute	Read an attribute value
set_attribute	Write an attribute value
list_attributes	List all configurable attributes on an object
get_object_info	Return area, host, container, hierarchy, and deployment status
list_deployment_view	Full deployment picture across the galaxy
create_instance	Create a new instance from a template
deploy_instance	Deploy an instance to its host engine

---

Lab Use

The lab walks participants through configuring the MCP server, exploring System Platform data via natural language, and extending the server with three new tools implementing a discover → create → deploy workflow.

The lab is designed to run on a local air-gapped network, demonstrating the full air-gapped AI stack to prospective customers.

---

Limitations and Known Constraints

• GRAccess is a configuration API. Runtime values (live PV data, scan state, alarm state) are not accessible through this interface. For live data, a separate MCP server targeting SuiteLink, OPC-UA, or the AVEVA Historian would be needed.
• 32-bit Python required. The MxValue COM class is registered only in the 32-bit COM registry and cannot be loaded by 64-bit Python.
• Concurrent IDE access. The ArchestrA IDE and GRAccess API share the galaxy's object lock manager. Running write operations while objects are open in the IDE can cause conflicts. Close the IDE before running create/deploy/set operations.
• Small model limitations. Models under 7B parameters can occasionally misinterpret multi-step queries or require rephrasing. IBM Granite 3.3 and Mistral Nemo perform well for this use case.

---

Roadmap Considerations

• Router-based architecture — separate read-only and write/control MCP servers to enable explicit safety boundaries and least-privilege access control
• Live data integration — additional MCP server targeting SuiteLink, OPC-UA or MQTT for runtime values alongside configuration data
• Audit logging — structured log of every tool call with arguments, user context, and result status (relevant for NERC CIP / IEC 62443 compliance discussions)
• Multi-galaxy support — session management to support switching between galaxies within a single conversation
• Alarm integration — MCP server for AVEVA Historian alarm data to enable natural language alarm analysis

---

License

MIT