winccoa-ae-js server

This MCP server provides an interface to connect AI assistants to WinCC OA SCADA systems, enabling intelligent automation and monitoring. It exposes a configurable set of tools that can read or modify WinCC OA data and configurations through the MCP protocol. The available tool categories include datapoints, archives, common configuration, PV ranges, managers, dashboards, OPC UA connections, MQTT, and more, with the ability to tailor which categories are enabled for a given deployment. By default you should operate in a read-only or restricted mode to minimize risk, and gradually enable more capable tools as you validate safety and access control. When used with Claude Desktop or Claude Code, you can issue natural-language queries such as querying temperatures, checking which pumps are running, adjusting setpoints, or generating production reports, and the MCP server will translate those requests into WinCC OA API calls.

To use the tools, configure the TOOLS environment in your .env file to include the categories you want enabled. For example, a safe starting point is a read-only setup with query capabilities across datapoints, archives, common queries, PV ranges, and manager listings. If you need write capabilities (e.g., to set datapoints or manage dashboards), you can enable those categories explicitly, but be sure to restrict permissions and test in a non-production environment. When connecting to Claude Desktop or Claude Code, provide the MCP authorization token that matches your environment (MCP_API_TOKEN) and the proper mcp-remote URL and headers. Note that remote hosts require the --allow-http flag in the Claude CLI/Config, and Windows users may need an alternate command path to avoid spaces in the executable path.

Operationally, you can start the MCP server in your project’s environment, then configure Claude or your chosen AI tool to connect to the MCP endpoint using the header token, and the server will mediate data access to WinCC OA according to the enabled tool categories.

Prerequisites:

• Node.js and npm installed on the host
• Access to WinCC OA project files and a compatible WinCC OA JavaScript environment
• An AI tool that supports MCP servers (e.g., Claude Desktop/Code)

1. Install in the WinCC OA javascript directory

• On Windows & Linux:

cd <OA_ProjPath>\javascript
mkdir mcpServer
cd mcpServer

2. Install required packages

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

3. Configure environment Create and edit the .env file from the template Windows:

cop .env.example .env
notepad .env

Linux/macOS:

cp .env.example .env
nano .env

Minimal .env setup (examples):

# Token must match the token configured in Claude Desktop
MCP_API_TOKEN=your-secure-token-here

WINCCOA_FIELD=default

# Example full feature set (adjust as needed)
TOOLS=datapoints/dp_basic,datapoints/dp_set,opcua/opcua_connection,mqtt/mqtt_connection,dashboards/dashboard,manager/manager_list

4. Start/Connect Manager in WinCC OA

• Add a JavaScript Manager in WinCC OA with Script Path:

mcpServer/index_http.js

5. Optional: Connect Claude Desktop/Code

• Use the provided sample configuration to connect Claude Desktop by adding an MCP server with the appropriate token header.
• For remote WinCC OA servers, append --allow-http where required.

6. Verify operation

• Ensure the CLI or Claude connection uses the same token as MCP_API_TOKEN and that the enabled TOOLS match the intended permissions.

Tips and common issues:

• Always keep a read-only baseline configuration (limited tools) before enabling write operations.
• Ensure the MCP_API_TOKEN in .env matches the Authorization header used by Claude Desktop/Code exactly.
• If you encounter Windows path issues for npx, you may need to configure the Windows-specific JSON with cmd /c as shown in the README example. This preserves spaces in paths.
• When connecting to a remote WinCC OA server, remember to add --allow-http to the mcp-remote arguments.
• The token-based authentication is essential for security; rotate tokens periodically and restrict access to trusted tools.
• Icon tools (icons/icon) only create/delete SVG files and do not modify SCADA data.
• If you need a read-only starting point, configure TOOLS with datapoints/dp_basic, datapoints/dp_types, archive/archive_query, common/common_query, pv_range/pv_range_query, manager/manager_list, and opcua/opcua_connection.