Beckhoff PLC MCP Server

An MCP (Model Context Protocol) server that provides read-only access to Beckhoff TwinCAT PLCs via ADS (Automation Device Specification).

Features

• Query PLC device information and state
• List and search PLC symbols
• Read single or multiple PLC variables
• Dynamic PLC discovery and connection via UDP (port 48899)
• EtherCAT diagnostics - master state, slave count, topology, and slave info
• Custom ADS port access - query and read from any ADS port (e.g., I/O Image ports)
• Graceful startup - server starts even if no local PLC is connected
• Automatic ADS route creation
• Automatic symbol caching for fast lookups
• Support for common TwinCAT data types

Prerequisites

• Python 3.10 or higher
• Beckhoff TwinCAT runtime with ADS enabled
• ADS routing configured (for remote PLCs)

Installation

# Clone or navigate to the project directory
cd beckhoff_mcp

# Install with pip
pip install -e .

# Or install dependencies directly
pip install mcp pyads pydantic

Uninstallation

To uninstall the current version before installing a new one:

# Uninstall the package
pip uninstall beckhoff_mcp

# Verify it's removed
pip show beckhoff_mcp

Configuration

Default Connection Settings

The server attempts to connect to a local TwinCAT PLC on startup:

AMS_NET_ID = "127.0.0.1.1.1"  # Localhost AMS Net ID
AMS_PORT = 851                 # TwinCAT 3 PLC Runtime 1

Note: If no local PLC is available (e.g., TwinCAT is not running or is in Config mode), the server will start in disconnected mode. You can then use beckhoff_discover_and_connect to connect to a remote PLC.

To modify the default settings, edit src/beckhoff_mcp/server.py and update the constants at the top of the file.

Dynamic Connection (Runtime)

You can also connect to remote PLCs at runtime using the beckhoff_discover_and_connect tool. Simply ask Claude to connect to a specific IP address:

<beckhoff:mcp: ip=192.168.1.54>

Or with credentials for automatic route creation:

Connect to PLC at 192.168.1.54 with username admin and password secret

Common AMS Port Numbers

| Port | Description | |------|-------------| | 851 | TwinCAT 3 PLC Runtime 1 | | 852 | TwinCAT 3 PLC Runtime 2 | | 853 | TwinCAT 3 PLC Runtime 3 | | 854 | TwinCAT 3 PLC Runtime 4 |

Usage

Running the Server

# Using the installed script
beckhoff_mcp

# Or run directly
python -m beckhoff_mcp.server

Claude Desktop Configuration

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "beckhoff_mcp": {
      "command": "python",
      "args": ["-m", "beckhoff_mcp.server"]
    }
  }
}

Or if installed as a package:

{
  "mcpServers": {
    "beckhoff_mcp": {
      "command": "beckhoff_mcp"
    }
  }
}

Available Tools

beckhoff_get_device_info

Get PLC device name and version information.

Input: None

Output: ``json { "device_name": "TwinCAT PLC", "version": { "major": 3, "minor": 1, "build": 4024 } } ``

beckhoff_get_device_state

Get current ADS state and device state.

Input: None

Output: ``json { "ads_state": { "code": 5, "name": "Run" }, "device_state": 0 } ``

beckhoff_list_symbols

List available PLC symbols with optional filtering and pagination.

Input:

• filter (optional): Filter pattern with wildcards (e.g., "GVL_", "Motor*")
• limit (optional, default 50): Maximum results to return
• offset (optional, default 0): Pagination offset

Output: ``json { "symbols": [ {"name": "GVL.bStart", "type": "BOOL", "comment": "Start button"}, {"name": "GVL.nCounter", "type": "INT", "comment": "Cycle counter"} ], "pagination": { "total": 150, "offset": 0, "limit": 50, "returned": 50, "has_more": true, "next_offset": 50 } } ``

beckhoff_get_symbol_info

Get detailed information about a specific symbol.

Input:

• symbol_name (required): Full symbol name (e.g., "MAIN.bStart")

Output: ``json { "name": "MAIN.bStart", "type": "BOOL", "index_group": 16448, "index_offset": 0, "size": 1, "comment": "Start button" } ``

beckhoff_read_variable

Read a single PLC variable by symbol name.

Input:

• symbol_name (required): Full variable name (e.g., "GVL.nCounter")

Output: ``json { "name": "GVL.nCounter", "type": "INT", "value": 42 } ``

beckhoff_read_variables

Read multiple PLC variables at once.

Input:

• symbol_names (required): List of variable names

Output: ``json { "results": [ {"name": "GVL.bStart", "type": "BOOL", "value": true}, {"name": "GVL.nCounter", "type": "INT", "value": 42} ], "errors": null, "summary": { "requested": 2, "successful": 2, "failed": 0 } } ``

beckhoff_discover_and_connect

Discover and connect to a remote PLC by IP address using UDP discovery.

Input:

• ip_address (required): IP address of the target PLC
• username (optional): PLC login for route creation
• password (optional): PLC password for route creation
• ams_port (optional, default 851): ADS port number
• route_name (optional): Custom name for the route

Output: ``json { "success": true, "ip_address": "192.168.1.54", "discovered_ams_net_id": "192.168.1.54.1.1", "ams_port": 851, "route_added": true, "device_info": { "device_name": "CX-12345", "version": {"version": 3, "revision": 1, "build": 4024} }, "symbols_cached": 150 } ``

beckhoff_connection_status

Get information about the current PLC connection.

Input: None

Output: ``json { "ams_net_id": "192.168.1.54.1.1", "ams_port": 851, "ip_address": "192.168.1.54", "is_remote": true, "is_connected": true, "symbols_cached": 150 } ``

EtherCAT Diagnostic Tools

beckhoff_get_ethercat_master_state

Get the EtherCAT master state (Init, PreOp, SafeOp, Op).

Input: None

Output: ``json { "master_state": {"code": 8, "name": "Op"}, "ams_net_id": "192.168.1.54.1.1", "ethercat_port": 65535 } ``

beckhoff_get_ethercat_slave_count

Get the number of connected EtherCAT slaves.

Input: None

Output: ``json { "slave_count": 5, "ams_net_id": "192.168.1.54.1.1" } ``

beckhoff_get_ethercat_topology

Get the full EtherCAT network topology with all slave information.

Input: None

Output: ``json { "slave_count": 3, "slaves": [ {"address": 1, "state": {"code": 8, "name": "Op"}, "vendor_id": 2, "product_code": 100663346}, {"address": 2, "state": {"code": 8, "name": "Op"}, "vendor_id": 2, "product_code": 100728882} ], "ams_net_id": "192.168.1.54.1.1" } ``

beckhoff_get_ethercat_slave_info

Get detailed information about a specific EtherCAT slave.

Input:

• slave_address (required): The slave address (1-indexed)

Output: ``json { "address": 1, "state": {"code": 8, "name": "Op"}, "vendor_id": 2, "product_code": 100663346, "crc_errors": 0, "ams_net_id": "192.168.1.54.1.1" } ``

Custom ADS Port Tools

Some EtherCAT devices (like EK1200 EtherCAT Couplers) expose their I/O data on custom ADS ports rather than the standard EtherCAT master port (0xFFFF). Use these tools to access such devices.

beckhoff_query_ads_port

Query a custom ADS port to discover available symbols and device information.

Input:

• ads_port (required): The ADS port number (e.g., 27905 or 0x6D01)

Output: ``json { "ads_port": 27905, "ads_port_hex": "0x6D01", "ams_net_id": "5.59.203.226.1.1", "ip_address": "192.168.1.67", "success": true, "device_info": { "device_name": "EK1200", "version": {"version": 3, "revision": 1, "build": 4024} }, "state": { "ads_state": {"code": 5, "name": "Run"}, "device_state": 0 }, "symbol_count": 4, "symbols_preview": [ {"name": "Inputs.EL1008.Channel 1.Input", "type": "BOOL"}, {"name": "Outputs.EL2008.Channel 1.Output", "type": "BOOL"} ] } ``

beckhoff_read_from_port

Read a variable from a custom ADS port.

Input:

• ads_port (required): The ADS port number (e.g., 27905)
• symbol_name (required): The symbol name to read

Output: ``json { "name": "Inputs.EL1008.Channel 1.Input", "type": "BOOL", "value": true, "ads_port": 27905 } ``

How to find the ADS port: In TwinCAT XAE, double-click on the device (e.g., under I/O > Devices > EtherCAT), go to the "ADS" tab, and note the "ADS Server Port" value.

Supported Data Types

| TwinCAT Type | Description | |--------------|-------------| | BOOL | Boolean (TRUE/FALSE) | | BYTE | 8-bit unsigned | | SINT | 8-bit signed | | USINT | 8-bit unsigned | | INT | 16-bit signed | | UINT | 16-bit unsigned | | DINT | 32-bit signed | | UDINT | 32-bit unsigned | | LINT | 64-bit signed | | ULINT | 64-bit unsigned | | REAL | 32-bit float | | LREAL | 64-bit float | | STRING | Text string | | TIME, DATE, DT, TOD | Time types (as UDINT) | | WORD, DWORD, LWORD | Bit string types |

Note: Complex types (arrays, structures) are not fully supported for reading. The server will return type information but may not be able to read the value directly.

Troubleshooting

Connection Errors

If you see connection errors:

1. Verify TwinCAT is running: Check that TwinCAT System Service is running and the PLC is in Run mode
2. Check AMS Net ID: Ensure the AMS Net ID in the server matches your system (run hostname in TwinCAT XAE to find it)
3. Verify ADS routing: For remote connections, ensure ADS routes are configured on both systems
4. Check firewall: ADS uses TCP port 48898 by default

Symbol Not Found

If symbols are not found:

1. Ensure the PLC project is activated and running
2. Check the exact symbol name including namespace (e.g., MAIN., GVL.)
3. Symbol names are case-sensitive
4. Try beckhoff_list_symbols with a filter to find the correct name

License

MIT License