WinCC OA MCP Server

Model Context Protocol server for WinCC OA - enables AI assistants to interact with WinCC OA projects

Features • Installation • Usage • Known Issues

Disclaimer: This is the first stable release (v1.0.0) of the WinCC OA MCP Server extension. Not all features are fully implemented and some functions may not work perfectly yet. Please report any issues you encounter. Tip: If the extension doesn't work as expected, try Ctrl+Shift+P → Reload Window to refresh.

🎯 Motivation

This extension provides a Model Context Protocol (MCP) Server for WinCC OA, acting as a bridge between AI assistants (like GitHub Copilot) and your WinCC OA projects.

Note: This extension uses the officially provided WinCC OA MCP Webserver interface developed by Siemens. The extension automates the installation, configuration, and integration of this official webserver into your VS Code workflow.

The goal is to enable developers to use natural language commands to:

🔍 Search and query datapoints
📊 List and monitor managers
📈 Get datapoint values and types
✅ Check manager status
🗂️ Analyze WinCC OA project structure
⚡ Execute CTL scripts

🎬 See It In Action

WinCC OA MCP Server Demo

✨ Features

🧙 Auto-Setup Wizard

One-Click Installation: Automatically clones, installs, and configures MCP Server
Smart Manager Installation: Post-setup dialog for WinCC OA manager configuration
- Automatic Mode: Writes manager to config/progs file with auto-assigned number
- Manual Mode: Shows comprehensive setup instructions
Auto-Number Assignment: Finds next free -num X number automatically
Restart Reminder: Clear instructions about project restart requirements

🔌 Persistent Client Architecture

Auto-Detection: Reads MCP configuration from project's .env file
Auto-Connect: Connects to MCP Server on extension activation
Auto-Reconnect: Monitors connection with configurable heartbeat
Project Integration: Seamless switching between WinCC OA projects

🤖 Language Model Tools

6 tools available for GitHub Copilot autonomous access:

list_managers - List all WinCC OA managers with status
search_datapoints - Search datapoints by pattern
get_datapoint_value - Get current datapoint values
get_datapoint_type - Get datapoint type information
get_manager_status - Get detailed manager status
execute_script - Execute CTL scripts with arguments

⚙️ User Settings

Configurable options in VS Code Settings:

Log Level: Filter log output (debug, info, warn, error)
Auto-Reconnect: Enable/disable automatic reconnection (default: true)
Reconnect Retries: Configure retry attempts 0-10 (default: 3)
Heartbeat Interval: Configure heartbeat check frequency 5s-5min (default: 30s)
Show Notifications: Toggle reconnect notifications (default: true)

📊 Status Bar UI

Connection Status: Live indicator (🪄 Connected / ⚠️ Disconnected)
QuickPick Menu: Click status bar for context-aware actions
- Connected: Show Server Info, Disconnect, Reconnect, Show Logs
- Disconnected: Connect, Run Setup, Show Logs

📥 Installation

Prerequisites

WinCC OA Project Admin Extension (required for automatic project detection)
WinCC OA 3.21+ (officially supported version)
Node.js 14+ (for MCP Server runtime)

From VS Code Marketplace

Open VS Code
Go to Extensions (Ctrl+Shift+X)
Search for "WinCC OA MCP Server"
Click "Install"

🚀 Setup

Automatic Setup (Recommended)

Install Extensions:
- Install WinCC OA MCP Server extension
- Install WinCC OA Project Admin extension (dependency)
Select Project:
- Open WinCC OA Project Admin view
- Select your project from the list
Run Setup Wizard:
- If MCP Server not found, extension prompts: "Run Setup Wizard"
- Click "Install" to start automatic installation
- Wait for progress: Clone → Install → Generate Token → Configure → Build
Add Manager (v1.1.0):
- After installation, dialog appears: "Add MCP Server manager?"
- Choose Automatic or Manual Instructions
Automatic Mode:
- Extension writes manager to config/progs file
- Auto-assigns next free manager number
- Shows restart reminder
Manual Mode:
- Webview panel with comprehensive instructions
- Two setup options:
  - Option 1 (Recommended): Via PMON Console
  - Option 2: Direct config/progs file editing
- Copy-ready manager options string
Restart WinCC OA Project:
- ⚠️ IMPORTANT: Close and reopen your WinCC OA project
- Manager will appear in PMON Console
- Manager starts automatically (start mode: always, 3 retries)
Verify Connection:
- Check status bar: Should show "🪄 WinCC OA Copilot"
- Click status bar → "Show Server Info" to verify

Manual Setup

If auto-setup fails or you prefer manual installation:

Click to expand manual setup steps

Clone MCP Server repository:

cd <your-project>/javascript
git clone https://github.com/winccoa/winccoa-ae-js-mcpserver.git mcpServer

Install dependencies and build:

cd mcpServer/mcpWinCCOA
npm install
npm run build

Create .env file in mcpWinCCOA/build/.env:

MCP_API_TOKEN=your-secure-token-here
MCP_MODE=http
MCP_HTTP_PORT=3001
MCP_HTTP_HOST=0.0.0.0
MCP_AUTH_TYPE=bearer
RATE_LIMIT_ENABLED=true
MCP_CORS_ENABLED=true
MCP_CORS_ORIGINS=*
WINCCOA_FIELD=default
TOOLS=datapoints/dp_basic,datapoints/dp_create,datapoints/dp_set,manager/manager_list,archive/archive_query

Add manager to PMON:

Option 1 - Via PMON Console (Recommended):
- Open PMON Console
- Click "Add Manager"
- Configure:
  - Component: node
  - Start Mode: always
  - Seconds to Kill: 30
  - Restart Count: 3
  - Reset Min: 1
  - Options: -num 2 mcpServer /path/to/mcpWinCCOA/build/index_http.js
Option 2 - Edit config/progs:
- Open <project>/config/progs
- Add this line (before comments):
```
node             | always |      30 |        3 |        1 |-num 2 mcpServer /path/to/mcpWinCCOA/build/index_http.js
```
- Save file and restart WinCC OA project
Restart WinCC OA Project

💡 Usage

With GitHub Copilot

Use natural language to interact with your WinCC OA project:

"Show me all datapoints with 'pump' in the name"
"What's the current value of System1:Tank.level?"
"List all running managers"
"Get the type information for ExampleDP_Arg1"
"Execute the test script in scripts/tests/myTest.ctl"

Click "🪄 WinCC OA Copilot" in the status bar to access:

When Connected:

📊 Show Server Info: View project, URL, and available tools
🔌 Disconnect: Close connection to MCP Server
🔄 Reconnect: Reconnect to server
📋 Show Logs: Open extension output channel

When Disconnected:

🔌 Connect: Connect to MCP Server
🛠️ Run Setup: Start MCP Server installation wizard
📋 Show Logs: Open extension output channel

Commands

Available via Command Palette (Ctrl+Shift+P):

WinCC OA: Connect to MCP Server
WinCC OA: Disconnect from MCP Server
WinCC OA: Reconnect to MCP Server
WinCC OA: Show Server Info
WinCC OA: Run Setup Wizard
WinCC OA: Show Logs

⚙️ Configuration

Essential Settings

Setting	Default	Description
`winccoa.mcp.logLevel`	`info`	Log verbosity: `debug`, `info`, `warn`, `error`
`winccoa.mcp.autoReconnect`	`true`	Enable automatic reconnection on connection loss
`winccoa.mcp.reconnectRetries`	`3`	Number of retry attempts (0-10)
`winccoa.mcp.heartbeatInterval`	`30000`	Heartbeat check interval in ms (5000-300000)
`winccoa.mcp.showNotifications`	`true`	Show notifications for reconnect events

💡 Tip: Set log level to debug when reporting bugs for detailed diagnostics.

🐛 Known Issues

Manager Installation

Project Restart Required:
- After adding MCP Server manager, the WinCC OA project must be restarted
- Manager will not appear in PMON until restart
- This is a WinCC OA limitation - config/progs is only read at startup
WinCC OA Complete Restart Sometimes Needed:
- ⚠️ Known Issue: Sometimes a simple project restart is not enough
- Symptom: Manager does not appear in PMON Console even after project restart
- Workaround: Close WinCC OA completely and reopen it
- Root Cause: WinCC OA caching issue with PMON configuration
- Recommendation: If manager doesn't appear after first restart, close and reopen WinCC OA

Connection & Auto-Reconnect

Initial Connection Delay:
- First connection after project start may take 2-3 seconds
- MCP Server needs time to initialize Node.js manager
Auto-Reconnect Notifications:
- Can be disabled in settings: winccoa.mcp.showNotifications
- Notifications appear during temporary connection loss (e.g., server restart)

🔧 Troubleshooting

Manager Not Appearing

Symptom: Manager not visible in PMON Console after restart

Solution:

Restart WinCC OA project again
If still not visible: Close WinCC OA completely and reopen
Verify entry in <project>/config/progs file
Check manager number is unique (no conflicts with existing managers)

Connection Failed

Symptom: Status bar shows "⚠️ WinCC OA Copilot" (red/yellow)

Solution:

Check MCP Server manager is running in PMON
Verify .env file exists: <project>/javascript/mcpServer/mcpWinCCOA/build/.env
Check port 3001 is not blocked by firewall
Check logs: Click status bar → "Show Logs"

Setup Wizard Fails

Symptom: Installation errors during setup wizard

Solution:

Check Node.js is installed: node --version
Check Git is installed: git --version
Check internet connection (for git clone and npm install)
Try manual setup (see Manual Setup)

📚 Requirements

VS Code: 1.108.0 or higher
WinCC OA: 3.21 or higher (officially supported)
Node.js: 14 or higher (for MCP Server runtime)
WinCC OA Project Admin Extension: Required for automatic project detection

� License

🙏 Acknowledgments

WinCC OA development team for the MCP Server implementation
GitHub Copilot team for Language Model Tools API
VS Code extension development community

WinCC OA MCP Server

RichardJanisch

WinCC OA MCP Server

🎯 Motivation

🎬 See It In Action

✨ Features

🧙 Auto-Setup Wizard

🔌 Persistent Client Architecture

🤖 Language Model Tools

⚙️ User Settings

📊 Status Bar UI

📥 Installation

Prerequisites

From VS Code Marketplace

🚀 Setup

Automatic Setup (Recommended)

Manual Setup

💡 Usage

With GitHub Copilot

Status Bar Menu

Commands

⚙️ Configuration

Essential Settings

🐛 Known Issues

Manager Installation

Connection & Auto-Reconnect

🔧 Troubleshooting

Manager Not Appearing

Connection Failed

Setup Wizard Fails

📚 Requirements

� License

🙏 Acknowledgments