winccoa/winccoa-ae-js-mcpserver

WinCC OA MCP Server

AI Integration for Industrial Automation

This Model Context Protocol (MCP) server connects AI assistants to WinCC OA SCADA systems, enabling intelligent automation and monitoring for industrial environments.

Quick Start

Ask your AI:

• "Show me all temperature values in the plant"
• "Which pumps are currently running?"
• "Set the setpoint for pump P-101 to 50%"
• "Create a production report for today"

⚠️ Warning

This tool can modify datapoint values in your WinCC OA system. Changes made through this MCP server directly affect your SCADA system and connected industrial processes. Use at your own risk and ensure proper testing in a safe environment before deploying to production systems.

To prevent write operations, exclude these tools from your configuration:

• datapoints/dp_set - Allows writing values to datapoints
• datapoints/dp_create - Allows creating new datapoints

Example read-only configuration:

# Only include read operations
TOOLS=datapoints/dp_basic,datapoints/dp_types

Prerequisites

This MCP server requires an AI tool that supports Model Context Protocol (MCP) servers. It works with any AI tool that has MCP support. For instructions on how to configure an MCP server in your specific AI tool, please refer to your tools documentation.

For this guide, we'll use Claude Desktop as an example. Download Claude Desktop

For detailed prerequisites, see .

1. Install

Navigate to your WinCC OA projects javascript directory and create a folder for the MCP server. You can choose any name for this folder - we'll use mcpServer in this guide:

Windows & Linux:

cd <OA_ProjPath>\javascript
mkdir mcpServer
cd mcpServer

Then install the required packages:

npm install @etm-professional-control/winccoa-mcp-server
npm install file:C:/Siemens/Automation/WinCC_OA/3.20/javascript/winccoa-manager

2. Configure

Create configuration file from template:

Windows:

copy .env.example .env
notepad .env

Linux/macOS:

cp .env.example .env
nano .env  # or use your preferred editor

Minimal .env setup:

# IMPORTANT: This token MUST match the token in Claude Desktop config!
# IMPORTANT: You can use any string as token (e.g., "my-secret-token-123")
# For better security, generate a random token:
# Windows:
#   - PowerShell: -join ((1..64) | ForEach {'{0:X}' -f (Get-Random -Max 16)})
#   - Node.js: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# Linux/macOS:
#   - openssl rand -hex 32
#   - pwgen 64 1
#   - node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
MCP_API_TOKEN=your-secure-token-here

# Choose industry context
WINCCOA_FIELD=default  # or 'oil', 'transport'

# Configure available tools  
TOOLS=datapoints/dp_basic,datapoints/dp_set,datapoints/dp_types

3. Start Server

Add JavaScript Manager in WinCC OA:

• Manager Type: JavaScript Manager
• Script Path: mcpServer/index_http.js

4. Connect Claude Desktop

To access the configuration file:

1. Open Claude Desktop
2. Click the menu (☰) in the upper left corner
3. Navigate to File → Settings
4. Go to the Developer section
5. Click "Edit Config" to open the configuration file

Edit the configuration file:

{
  "mcpServers": {
    "winccoa": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3000/mcp", "--header", "Authorization: Bearer YOUR_TOKEN_HERE"]
    }
  }
}

⚠️ IMPORTANT: Replace YOUR_TOKEN_HERE with the exact same token from your .env file's MCP_API_TOKEN. The tokens must match exactly!

Windows Path Issue: If you encounter the error "C:\Program" is either misspelled or could not be found, use this alternative configuration:

{
  "mcpServers": {
    "winccoa": {
      "command": "cmd",
      "args": ["/c", "npx", "mcp-remote", "http://localhost:3000/mcp", "--header", "Authorization: Bearer YOUR_TOKEN_HERE"]
    }
  }
}

This method uses cmd to properly handle paths with spaces in Windows.

Note: After modifying the configuration, you must restart Claude Desktop completely:

• On Windows: Close Claude through the task-tray menu by selecting "Exit", or end the task in Task Manager if needed
• On macOS/Linux: Quit Claude Desktop completely and restart

Documentation

• - Complete setup instructions
• - All .env options and server modes
• - Available tools and custom development
• - Industry templates and project customization
• - Common issues and limitations

Features

✅ Secure API - Token-based authentication
✅ Industry Templates - Pre-configured for Oil & Gas, Transportation
✅ Custom Tools - Extend with your own WinCC OA integrations
✅ Project Rules - Plant-specific AI guidance
✅ Dynamic Loading - Configure only needed tools

Support

• Repository: GitHub
• Issues: Report Bug
• WinCC OA Docs: Official Documentation

License

ISC - See LICENSE.md for details.