yudaikitamura/mcpx

日本語 | English

Website & documentation: mcpx.yktmr.jp — overview, API reference, and an MC protocol guide.

McpX is a library for communicating with Mitsubishi Electric PLCs using the MC protocol.
It features a simple and easy-to-use API, allowing you to communicate without worrying about MC protocol details.
It runs on various platforms, including Linux, Windows, and macOS.

Upgrading from 0.x? See the migration guide.

Installation

.NET CLI

dotnet add package McpX

Package Manager(Visual Studio)

PM> NuGet\Install-Package McpX

Example Usage

using McpXLib;
using McpXLib.Enums;

// Connect to the PLC (TCP / binary code / 3E frame / MELSEC-Q/L series by default)
using var mcpx = McpX.Connect("192.168.12.88", 10000);

// Read 7000 points starting from M0 (requests over the limit are split automatically)
bool[] mArr = mcpx.BatchRead(Prefix.M, "0", 7000);

// Read 7000 words starting from D1000
short[] dArr = mcpx.BatchRead(Prefix.D, "1000", 7000);

// Write 1234 to D0-D1 and 5678 to D2-D3 as signed 32-bit integers
mcpx.BatchWrite(Prefix.D, "0", [1234, 5678]);

// Read a range and single devices together (ranges: batch access, single: random access)
short[] block = [];
int total = 0;
mcpx.Read(b => b
    .Add(Prefix.D, "400", 100, v => block = v)
    .Add(Prefix.D, "2000", v => total = v));

Every method has an async version that takes a CancellationToken:

await using var mcpx = await McpX.ConnectAsync("192.168.12.88", 10000, cancellationToken);
short d0 = await mcpx.ReadAsync(Prefix.D, "0", cancellationToken);

C# and Visual Basic samples are available here.

Connection Settings

Pass McpXOptions to McpX.Connect / McpX.ConnectAsync to match the PLC parameters.

using var mcpx = await McpX.ConnectAsync(new McpXOptions
{
    Host = "192.168.12.89",
    Port = 5007,
    ProcessorSeries = ProcessorSeries.iQR,  // MELSEC iQ-R series (extended device specification)
    RequestFrame = RequestFrame.E4,
    IsAscii = false,
    IsUdp = false,
    Timeout = TimeSpan.FromSeconds(3),
    Password = "1234",                      // remote password (unlocked on connect, locked on dispose)
});

Accessing Other Stations

Specify McpXRoute (network No., PC No., request destination module I/O No. and station No.) to access another station on the network or another CPU of a multiple CPU system.

// Station with network No. 1 / PC No. 2
var options = new McpXOptions { Host = "192.168.12.89", Port = 5007, Route = new McpXRoute(networkNo: 1, pcNo: 2) };

// CPU No. 2 of the multiple CPU system the connected module belongs to
options.Route = McpXRoute.ForCpu(2);

Connecting to GX Simulator3

McpXSimulator connects to GX Simulator3 (the simulation function of GX Works3) by system No. and CPU No. The port is 5500 + system No. × 10 + CPU No. (e.g. system 1 / CPU 1 = 5511, system 2 / CPU 1 = 5521). Connect once per simulator to connect to several simulators at the same time. The returned object is a regular McpX.

using var sim1 = McpXSimulator.Connect();                                   // 127.0.0.1:5511 (system 1 / CPU 1)
using var sim2 = McpXSimulator.Connect(systemNo: 2, host: "192.168.12.90"); // 192.168.12.90:5521
using var cpu2 = await McpXSimulator.ConnectAsync(systemNo: 1, cpuNo: 2);   // 127.0.0.1:5512 (CPU No.2 of a multiple CPU system)

// To change other settings, start from CreateOptions
var options = McpXSimulator.CreateOptions(systemNo: 1, cpuNo: 1);
options.Timeout = TimeSpan.FromSeconds(10);
using var sim3 = McpX.Connect(options);

GX Simulator3 listens on 127.0.0.1 only. To connect from another PC, forward each port to 127.0.0.1 on the simulator PC (e.g. netsh interface portproxy). Communication is TCP / binary code only (GX Simulator3 does not respond to ASCII code).

Supported Commands

Every async method also takes an optional CancellationToken.

T can be bool, short, ushort, int, uint, float, long, ulong, double, byte and sbyte (byte / sbyte use one word each). Random access and monitoring support bool, short, ushort, int, uint and float.

Errors and Thread Safety

• A PLC error code throws McProtocolException (ErrorCode has the end code), an invalid address throws DeviceAddressException, and a malformed response throws ReceivePacketException. They derive from McpXException.
• A timeout throws TimeoutException. After a timeout, communication error or cancellation over TCP, the connection is closed and later calls throw IOException; connect again.
• Calling a method after Dispose throws ObjectDisposedException.
• A McpX instance can be called from several threads and tasks at the same time; requests are sent one at a time. An operation split into several requests (such as a large batch read) may be interleaved with other requests.

Supported PLCs and Protocols

PLC Parameter Settings

When using the built-in Ethernet port, set the parameters in GX Works3 as follows.

Versioning

McpX follows Semantic Versioning from 1.0.0. Breaking changes to the public API are made only in a major version.

Native Library (C ABI)

A native library (mcpx.dll / mcpx.so / mcpx.dylib) that exposes McpX as C functions. It does not require the .NET runtime and can be used from any language with an FFI, such as Python (ctypes) and Node.js (koffi). The native libraries are attached to each release. The header is McpXInterop/include/mcpx.h. It supports single, batch, random and multiple block access, strings, monitoring and remote operations, and is built for Windows x64 / Linux x64 and arm64 / macOS arm64. Every function returns a status code (MCPX_OK = 0) and writes the details (including the PLC end code) to mcpx_error on failure.

#include "mcpx.h"

mcpx_connect_options options;
mcpx_connect_options_init(&options);
options.host = "192.168.12.88";
options.port = 10000;

mcpx_error err = { .struct_size = sizeof(mcpx_error) };
mcpx_client_t plc;
if (mcpx_connect(&options, &plc, &err) == MCPX_OK)
{
    int16_t values[10];
    if (mcpx_batch_read(plc, MCPX_PREFIX_D, "0", MCPX_TYPE_I16, 10, values, sizeof(values), &err) != MCPX_OK)
    {
        printf("%s\n", err.message);
    }
    mcpx_close(plc, &err);
}

Roadmap

• [x] 3E frame (ASCII code) support
• [x] 4E frame (binary code) support
• [x] 4E frame (ASCII code) support
• [x] UDP support
• [x] GX Simulator support
• [x] Access to other stations
• [ ] Python / Node.js wrappers - In preparation

Changelog

• CHANGELOG.md

Related

• mcpx-mcp-server An MCP(Model Context Protocol) server that enables real-time access to Mitsubishi Electric PLC devices from generative AI.