WinCC OA MCP Server

A Model Context Protocol (MCP) server that exposes WinCC OA operations as LLM-callable tools. It runs inside a WinCC OA Node.js Manager and uses the native winccoa-manager add-on to interact with the WinCC OA runtime.

Features

• Datapoints — read/write values, create/delete/copy DPs, name discovery, SQL-like queries, timed/period writes
• DP types — list, inspect, create, change, delete types; name validation
• Archive — historical value queries and archive configuration
• Alarms — binary/non-binary alarm config and alarm log queries
• Common metadata — alias, description, unit, format
• PV range — engineering min/max limits for numeric DPEs
• Manager / PMON — list, status, start/stop/restart/kill, add/remove, properties, system info
• OPC UA — connection CRUD, address mapping, namespace browse
• ASCII — DPL export/import via WCCOAascii
• CTRL scripts — execute inline or file-based CTRL with log capture
• Address / distrib / smooth / dp_fct — peripheral and config management

Full parameter reference: docs/TOOLS.md (57 tools across 14 categories).

Tool overview

Registered tool names use the form category.tool_name (e.g. datapoints.dp_get).

Prerequisites

• WinCC OA 3.20 (or compatible) with the Node.js Manager enabled
• Node.js 18+ (bundled with WinCC OA or system-installed)
• The winccoa-manager native add-on (provided by the WinCC OA runtime – not on npm)

Installation

cd winccoa-mcp-server
npm install
npm run build

This bundles TypeScript sources from src/ into dist/index.js and copies .env.example to dist/.

Configuration

Since the WinCC OA Node.js Manager does not support command-line arguments, all configuration is done through a `.env` file placed next to the built entry point (or in the working directory).

Copy .env.example as a starting point. Minimal example:

# Transport mode: "stdio" or "http"
MCP_TRANSPORT=stdio

# Port for the HTTP transport (only used when MCP_TRANSPORT=http)
# Default 47899 avoids conflicts with common Node.js apps on port 3000
MCP_HTTP_PORT=47899

# Maximum response size in characters to prevent overwhelming the LLM context
MCP_CHARACTER_LIMIT=25000

Full reference (CORS, SSL, rate limits, IP filter, field profiles): docs/CONFIGURATION.md.

Usage

stdio transport (default)

The server communicates over stdin / stdout. Use this when the MCP client (e.g. Claude Desktop, VS Code) starts the process directly or when testing with MCP Inspector.

node dist/index.js

HTTP transport

Set MCP_TRANSPORT=http in your .env file, then start the server. It will listen on the port specified by MCP_HTTP_PORT (default 47899).

node dist/index.js

Endpoints:

• POST /mcp — MCP protocol (auth required when enabled)
• GET /health — health check (no auth)

Integration with WinCC OA

This server is designed to be run as customer code inside a WinCC OA Node.js Manager. The typical setup:

1. Place the built dist/ folder (or the whole project) in your WinCC OA project's scripts directory.
2. Configure a Node.js Manager in the WinCC OA console with this server as the entry script.
3. The WinCC OA bootstrap will load the native winccoa-manager add-on, then execute dist/index.js.

MCP client configuration

#### Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "winccoa": {
      "command": "node",
      "args": ["C:/path/to/winccoa-mcp-server/dist/index.js"]
    }
  }
}

#### VS Code (.vscode/mcp.json)

{
  "servers": {
    "winccoa": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/path/to/winccoa-mcp-server/dist/index.js"]
    }
  }
}

For HTTP transport, point the client to http://localhost:47899/mcp (or your configured port) and supply the bearer/API token as configured.

Development

# Typecheck
npm run typecheck

# Unit tests
npm test

# Build bundle
npm run build

# Test with MCP Inspector
npm run inspect

To switch transports during development, edit the .env file.

Project structure

src/
├── index.ts                 # Entry point – transport setup
├── server.ts                # McpServer creation + resources
├── constants.ts             # Shared constants (port, tool filter, limits)
├── winccoa-client.ts        # WinccoaManager singleton
├── config/
│   └── server-config.ts     # HTTP security config from env
├── pmon/                    # PMON TCP client for manager tools
├── types/
│   └── winccoa-manager.d.ts # Type declarations for native add-on
├── tools/
│   ├── register-all.ts      # Tool registration orchestrator
│   ├── datapoints/          # DP read/write/create/query tools
│   ├── dp-types/            # DP type management tools
│   ├── archive/             # Historical data + archive config
│   ├── alarms/              # Alarm config + log
│   ├── common/              # Alias/description/unit/format
│   ├── pv-range/            # Engineering range
│   ├── manager/             # PMON manager lifecycle + system info
│   ├── opcua/               # OPC UA connections, address, browse
│   ├── ascii/               # ASCII export/import
│   ├── script/              # CTRL script execution
│   ├── address/             # Peripheral address config
│   ├── distrib/             # Distribution config
│   ├── smooth/              # Smoothing config
│   └── dp-fct/              # Datapoint function config
├── resources/
│   ├── systemprompt.md      # LLM system instructions
│   ├── conventions.md       # Naming conventions resource
│   └── fields/              # Industry field guidelines
└── utils/                   # Error handling, formatters, helpers

See docs/ARCHITECTURE.md for request flow and middleware details.

Adding new tools

1. Create src/tools/<category>/your-tool.ts following the existing pattern (Zod schema + registerTool()).
2. Register the tool with a canonical name category.tool_name (dot separator).
3. Import and call your registration function in src/tools/register-all.ts.
4. Add the name to the correct category list in the CATEGORIES map.
5. Add unit tests next to the tool file and a section in docs/TOOLS.md.
6. Rebuild with npm run build.

Documentation

License

MIT