BnR-MCP-Server

Unified MCP (Model Context Protocol) server for B&R Automation Studio — build projects, connect to PLCs, read/write variables, trend data, generate charts, and query a local variable database, all from Claude or any MCP-compatible AI assistant.

38 tools | TypeScript + C# companion | SQLite variable index | MIT License

---

Features

| Category | Tools | Description | |----------|-------|-------------| | Build | 4 | Build AS6 projects, transfer to target, parse build logs | | Connect | 5 | ANSL/TCP connection to PLC or ARSim, auto-detect, ping, switch target | | Variables | 4 | Read/write scalars, structs, arrays, batch operations | | Variable DB | 3 | SQLite-backed variable index — fast query without PLC round-trip | | Watch | 6 | Poll variables, list sessions, export CSV, live web dashboard | | Fast Trend | 3 | High-frequency monitoring (10-100ms) via C# companion + PNG charts | | PLC Info | 4 | CPU info, task list, module list, error logbook | | Modules | 3 | Upload/download/compare .br module files | | Control | 3 | Coldstart, warmstart, diagnostics mode (with safety confirmation) | | Workflow | 2 | One-shot deploy workflow, full health report |

Prerequisites

Required

| Dependency | Version | Purpose | |------------|---------|---------| | B&R Automation Studio 6 | AS6 | Provides BR.AS.Build.exe and PVITransfer.exe | | B&R PVI 6 | PVI 6.x | PLC communication runtime (installed with AS6) | | Node.js | 18+ | MCP server runtime | | npm | 9+ | Package manager |

Optional (for high-frequency trending)

| Dependency | Version | Purpose | |------------|---------|---------| | .NET Framework 4.8.1 | x86 | Required by BR.AN.PviServices.dll | | MSBuild / dotnet CLI | .NET SDK 8.0+ | Building the C# companion | | Windows | 10/11 | PVIServices is Windows-only (x86) |

Important: BR.AN.PviServices.dll is a PE32 (x86) .NET Framework assembly. It does not work under .NET 8.0 x64. The companion must target net481 with PlatformTarget=x86.

Auto-Detected Paths

The server auto-detects B&R installation paths. Override with environment variables if needed:

| Component | Default Locations | |-----------|-------------------| | BR.AS.Build.exe | C:\Program Files (x86)\BrAutomation\AS6\bin-en\BR.AS.Build.exe | | PVITransfer.exe | C:\Program Files (x86)\BrAutomation\PVI6\PVI\Tools\PVITransfer\PVITransfer.exe | | PviCompanion.exe | companion\bin\Release\net481\PviCompanion.exe (relative to project) |

Installation

# Clone
git clone https://github.com/your-username/BnR-MCP-Server.git
cd BnR-MCP-Server

# Install dependencies
npm install

# Build TypeScript
npm run build

# (Optional) Build C# companion for high-frequency trending
npm run build:companion
# or manually:
dotnet build companion/PviCompanion.csproj -c Release

Configuration

Claude Desktop / Claude Code

Add to your MCP settings (claude_desktop_config.json or Claude Code settings):

{
  "mcpServers": {
    "bnr": {
      "command": "node",
      "args": ["C:/path/to/BnR-MCP-Server/dist/index.js"],
      "env": {
        "PVI_PLC_IP": "192.168.0.10",
        "BR_PROJECTS_ROOT": "C:/Users/you/projects"
      }
    }
  }
}

Environment Variables

All configuration is optional — sensible defaults are provided.

| Variable | Default | Description | |----------|---------|-------------| | BR_BUILD_EXE | (auto-detect) | Path to BR.AS.Build.exe | | BR_PROJECTS_ROOT | Current directory | Root directory for project scanning | | BR_BUILD_TIMEOUT_MS | 300000 (5 min) | Build timeout in milliseconds | | BR_EXCLUDED_DIRS | node_modules,Temp,Binaries,.git | Directories to skip when scanning | | PVI_TRANSFER_EXE | (auto-detect) | Path to PVITransfer.exe | | PVI_PLC_IP | 192.168.0.10 | Default PLC IP address | | PVI_WAIT_TIME | 30 | Connection timeout in seconds | | PVI_TEMP_DIR | %TEMP%/pvi-mcp | Temp directory for PIL scripts | | PVI_WATCH_MAX_SAMPLES | 3600 | Max samples per watch session | | PVI_COMPANION_EXE | (auto-detect) | Path to PviCompanion.exe | | BNR_DB_PATH | %TEMP%/pvi-mcp/bnr-mcp.db | SQLite database path |

Total Workflow

The complete development-to-debugging cycle using BnR-MCP-Server:

┌─────────────────────────────────────────────────────────────────────────┐
│                        TOTAL WORKFLOW                                  │
│                                                                       │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐            │
│  │ 1.SETUP │───▶│ 2.BUILD │───▶│3.CONNECT│───▶│ 4.DEBUG │            │
│  └─────────┘    └─────────┘    └─────────┘    └─────────┘            │
│       │              │              │              │                   │
│       ▼              ▼              ▼              ▼                   │
│  Install &      Build AS6      Connect to     Read/Write              │
│  Configure      Project        PLC/ARSim      Variables               │
│                                                    │                   │
│                                          ┌─────────▼─────────┐        │
│                                          │  5. VAR DATABASE  │        │
│                                          │  Refresh + Query  │        │
│                                          └─────────┬─────────┘        │
│                                                    │                   │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌───▼─────┐            │
│  │9.CONTROL│◀───│8.EXPORT │◀───│ 7.CHART │◀───│ 6.TREND │            │
│  └─────────┘    └─────────┘    └─────────┘    └─────────┘            │
│       │              │              │              │                   │
│       ▼              ▼              ▼              ▼                   │
│  Restart PLC    CSV / Web       PNG Chart     Watch & Fast            │
│  Diagnostics    Dashboard       OxyPlot       Trend (10ms+)           │
│                                                                       │
└─────────────────────────────────────────────────────────────────────────┘

Step 1 — Setup

npm install && npm run build          # Build MCP server
npm run build:companion               # (Optional) Build C# companion

Add MCP server to Claude config → ready to use.

Step 2 — Build Project

"Build my project"
  → list_projects        Find .apj files in workspace
  → get_project_info     Check configurations
  → build_project        Build (mode: Build / Rebuild / BuildAndTransfer)
  → parse_build_log      Review errors & warnings

┌──────────────────────────────────────────────────────────────┐
│  AS6 Project (.apj)                                         │
│                                                             │
│  ┌─────────┐    ┌──────────────┐    ┌───────────────────┐   │
│  │ Sources │───▶│BR.AS.Build.exe│───▶│ Build Output      │   │
│  │ .st .c  │    │              │    │ ✓ 0 = Success     │   │
│  └─────────┘    │ -buildMode   │    │ ⚠ 1 = Warnings   │   │
│                 │  "Build"     │    │ ✗ 3 = Errors      │   │
│                 │  "Rebuild"   │    └───────────────────┘   │
│                 │  "BuildAnd   │             │               │
│                 │   Transfer"  │             ▼               │
│                 └──────────────┘    ┌───────────────────┐   │
│                                    │ parse_build_log    │   │
│                                    │ → structured JSON  │   │
│                                    └───────────────────┘   │
└──────────────────────────────────────────────────────────────┘

BuildAndTransfer — builds the project and transfers the installation package to the connected target (ARSim or real PLC). This is the B&R standard "Transfer to target" mechanism:

Sources → BUILD → Modules (.br) → PACK → Installation Package → TRANSFER → PLC

Step 3 — Connect to PLC

"Connect to my PLC"
  → pvi_ping             Quick TCP probe to check reachability (~2s)
  → pvi_auto_connect     Try hardware PLC first (if PVI_PLC_IP set), then ARSim
  → pvi_connect          Manual: specify IP address
  → pvi_switch_target    Switch between hardware PLC and ARSim in one call
  → get_config           Verify paths and connection state

┌───────────────────────────────────────────────────────────────┐
│  Connection Flow (pvi_auto_connect with PVI_PLC_IP set)      │
│                                                              │
│       ├──▶ Try PVI_PLC_IP (hardware) ──────▶ Connected?      │
│       │         │                              │             │
│       │         │ No                          Yes ──▶ Done   │
│       │         ▼                                            │
│       └──▶ Try 127.0.0.1:11169 (ARSim) ──▶ Connected?       │
│                                               │              │
│                                   Yes ──▶ Done │              │
│                                                              │
│  Response: CPU type, AR version, PLC status, IP source       │
└───────────────────────────────────────────────────────────────┘

Step 4 — Debug (Read/Write Variables)

"What is the current temperature?"
  → pvi_read_variable            Read single variable (scalar/struct/array)
  → pvi_write_variable           Write single variable with read-back
  → pvi_write_variables_batch    Write multiple variables at once

┌─────────────────────────────────────────────────────────────────┐
│  Variable Access Patterns                                      │
│                                                                │
│  Scalar:    pvi_read_variable { name: "gTemperature" }         │
│                                                                │
│  Struct:    pvi_read_variable { name: "stSensor",              │
│                                 member: "rValue",              │
│                                 task: "Control" }              │
│                                                                │
│  Array:     pvi_read_variable { name: "aValues", index: 3 }   │
│                                                                │
│  Nested:    pvi_read_variable { name: "stBatch",               │
│                                 member: "aSensors[0].rValue" } │
│                                                                │
│  Batch:     pvi_write_variables_batch {                        │
│               variables: [                                     │
│                 { name: "gSetpoint", value: "75.0" },          │
│                 { name: "gMode",     value: "2"    }           │
│               ]                                                │
│             }                                                  │
└─────────────────────────────────────────────────────────────────┘

Step 5 — Variable Database (SQLite Index)

Build a local variable index for fast, offline querying without hitting the PLC each time.

"Show me all REAL variables in HMIMain"
  → pvi_refresh_variables    Fetch variables from PLC → store in SQLite
  → pvi_query_variables      Fast SQL query (no PLC round-trip)
  → pvi_db_status            Check DB health and last refresh time

┌──────────────────────────────────────────────────────────────────┐
│  Variable Database Workflow                                     │
│                                                                 │
│  Once:   pvi_refresh_variables { scope: "all" }                 │
│              → fetches globals (VariableListGlobal)             │
│          pvi_refresh_variables { scope: "local",                │
│                                  task: "HMIMain" }              │
│              → fetches task-local variables                     │
│                                                                 │
│  Anytime (fast):