purinzan/gx3-cli-mcp

日本語 · English · 简体中文 · 한국어
**Work out why a coil never turns on, without opening GX Works3.**
Reads a GX Works3 .gx3 project on your own machine and answers questions
about it — where a device is written, what has to be true for a coil to turn
on, which conditions come from outside the PLC, which branches can never be
true. Read-only: it never writes back to the project.
It is a CLI, and the same analysis is a stdio MCP server, so an AI agent can
answer from indexed facts instead of guessing at a binary file.
日本語: 三菱電機 MELSEC の .gx3 を GX Works3 を開かずに解析する CLI / MCP
サーバーです。「このコイルがなぜ ON にならないか」をラダーから追います。
読み取り専用で、元のプロジェクトは書き換えません。
中文: 不用打开 GX Works3，也能分析三菱电机 MELSEC 的 .gx3 工程，
从梯形图追查「这个线圈为什么不导通」。只读，不改写原工程。
完整中文说明见 README.zh-CN.md。
---
Install
Python 3.10+. Installs two console scripts: gx3-cli and gx3-mcp-server.
Try it in 30 seconds
No project needed — generate one:
guide reads the project and tells you which commands are worth running on it,
and why. That is the answer to "there are sixty commands, where do I start".
On a project
Then ask it something:
Every command takes --format json for scripting, and -o FILE to write
instead of print. gx3-cli --help lists all of them by group.
Passing a .gx3 extracts it to .gx3_cache/ / and analyses that copy.
What it can tell you
| Question | Command |
|---|---|
| Why is this coil off? | trace-device, interlock-check |
| Where is this device written or read? | xref where-used, xref downstream |
| What does this program do? | rung-text, ladder-print, metrics |
| Show me the rung as a picture | ladder-layout --format svg |
| What comes from outside the PLC? | external-inputs, comm-refresh |
| What can never be true? | dead-logic |
| What looks wrong? | lint PROJECT (duplicate coils, multi-writer, operand widths, types) |
| What changed between versions? | diff, semantic-diff |
| Did it read the project correctly? | roundtrip |
Use with an AI agent
Or "command": "python", "args": ["-m", "gx3cli.gx3_mcp_server"] if your
client cannot resolve console scripts from PATH. The server exposes read-only
analysis tools and a restricted command runner.
See Agent usage guide (JA) for how an agent should
drive it.
Scope, honestly
Read-only analysis of ladder data in local .gx3 projects.
It does not edit projects, connect to a PLC to change anything, or replace GX
Works3. live-read can read live device values over MC Protocol/SLMP, CLI-only
and only with explicit connection parameters.
Output is advisory. Verify in GX Works3 and through your own safety process
before touching real equipment.
If a project fails to parse, gx3-cli failure-corpus capture turns it into a
local regression sample without sending anything anywhere.
Troubleshooting
**7z-style .gx3** — install 7-Zip, or point at it:
set GX3_7Z=C:\Program Files\7-Zip\7z.exe. Encrypted containers are not
decrypted; export the folder from GX Works3 instead.
**PyPI blocked** — pip install git+https://github.com/purinzan/gx3-cli-mcp.git
**Something reads wrong** — gx3-cli doctor --root ... first, then
open an issue.