gx3-mcp-server
Read-only analysis of Mitsubishi GX Works3 .gx3 ladder projects — trace why a coil won't turn on, cross-reference devices, lint, diff revisions, and inspect offline logs, all without opening GX Works3 or touching the project.
Trace device logic (
gx3_trace_device) — exact ON/OFF/hold conditions for a device, with MS master-control zones folded in and warnings for multi-coil devices.Check interlocks (
gx3_interlock_check) — whether two coils can be ON simultaneously; sound verdicts on mutual exclusion, witness assignments otherwise.Cross-reference (
gx3_xref_where_used) — every writer and reader of a device with POU name and step (needs the xref DB).Data flow (
gx3_data_flow) — conservative argument-level source→dest value-flow edges, with unknown operations reported unresolved.Lint (
gx3_lint) — duplicate coils, multi-writers, alarm quality, unused devices, contradictory comments, type/width problems.Dead logic (
gx3_dead_logic) — contacts that can never close, write-only words, SET latches with no RST.Device map (
gx3_device_map) — usage, density and free gaps per device type.Alarm map (
gx3_alarm_map) — what raises each alarm, whether it latches, and how it clears.Semantic diff (
gx3_semantic_diff) — rung-level added/removed/changed between two project versions, matched by block GUID.Network map (
gx3_network_map) — IPs, CC-Link/SCON stations and safety relations, read from project files only.Render ladder (
gx3_ladder_print) — GX Works3 print-text layout, filterable by section, step range or device.Snapshot explain (
gx3_explain_snapshot) — match a captured device snapshot against traced enable conditions (file-only, never connects to a PLC).Replay capture (
gx3_replay_capture) — normalize, series, changes or snapshot-export from an already-captured CSV/JSON log.Discover & run commands (
gx3_list_commands,gx3_run_command) — list read-only CLI commands, then run any allowed one as an escape hatch; mutating and demo-generation commands are rejected.
Provides read-only analysis tools for Mitsubishi Electric GX Works3 (.gx3) PLC projects, enabling inspection of project structure, device usage, cross references, ladder conditions, communication boundaries, and static quality signals.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gx3-mcp-server trace device M100 in the demo project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
gx3-cli-mcp
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
pip install gx3-cli-mcpPython 3.10+. Installs two console scripts: gx3-cli and gx3-mcp-server.
Related MCP server: PCM MCP
Try it in 30 seconds
No project needed — generate one:
gx3-cli synthetic-project demo.gx3 --profile demo-line
gx3-cli guide --root demo.gx3guide 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
gx3-cli doctor --root project.gx3 # does it read?
gx3-cli index-lite build --root project.gx3
gx3-cli xref build --root project.gx3
gx3-cli guide --root project.gx3 # what to run nextThen ask it something:
# where is this device written, and what reads it?
gx3-cli xref where-used M100 --root project.gx3
# why is this coil not turning on?
gx3-cli trace-device M100 --root project.gx3 --strict-logic --compact
# the whole program, one line per rung
gx3-cli rung-text --root project.gx3
# search the comment you remember, not the device number you don't
gx3-cli query-comment "clamp pressure" --root project.gx3Every 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/<sha256>/ and analyses that copy.
What it can tell you
Question | Command |
Why is this coil off? |
|
Where is this device written or read? |
|
What does this program do? |
|
Show me the rung as a picture |
|
What comes from outside the PLC? |
|
What can never be true? |
|
What looks wrong? |
|
What changed between versions? |
|
Did it read the project correctly? |
|
Use with an AI agent
{
"mcpServers": {
"gx3": { "command": "gx3-mcp-server" }
}
}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.
Documentation
User manual (JA) / (EN) / (ZH)
Ladder practical tips (JA) — field-oriented modification and review tips
Security note (JA) — local data handling, read-only MCP policy
Verification tracking — verification tasks and acceptance criteria
Independent validation ledger (JA) — GX Works3 evidence tracked for Issue #49
Doctor acceptance ledger (JA) — project-health acceptance tracked for Issue #135
GX Works3 feature matrix (JA) — standard-feature coverage, gaps, and implementation priorities
File usage guide (JA) — repository map
Analysis benchmark (JA) — synthetic performance baseline and measurement limits
Review questions (JA) — the questions to ask a change before opening a pull request, and the bugs each of them found
Related projects (JA) — other GX Works3/MELSEC tools and what was taken from them
llms.txt — machine-readable summary of what this is and is not
Agent skills: existing project audit · failure corpus
Analysis contract migration
Current query-by-query status and remaining acceptance work for #153: 解析契約の移行台帳.
License
Source-available, not open source. Full terms in LICENSE.txt; this is a summary and the license text governs.
You may read the source and run it for evaluation and internal work, including inside a company. You may not redistribute it, host it as a service, or ship it in a paid product without written permission. There is no licence key, activation or paid plan.
日本語: 社内での評価・業務利用は許諾されています。禁止しているのは再配布、 SaaS 提供、有償製品への組み込みです。実行にライセンスキーや課金は不要です。 商用利用の相談は Issue からどうぞ。
Listed on Glama
Indexed as an MCP server, with per-tool scores for how well each tool describes what it does. Useful as outside feedback on the tool surface — the low scores there are the ones whose descriptions need work.
Contributing: CONTRIBUTING.md · AGENTS.md
For ladder CSV input, use gx3-cli rung-text --csv ladder.csv. See the
CSV parser guide for verified scope and limitations.
Available Tools
15 toolsgx3_alarm_mapA
Inventory every alarm and fault device with what triggers it, whether it latches, any timer setpoint, and what resets it. Answers "what raises this alarm and how is it cleared" without reading the ladder by hand. Reads the project; WRITES a CSV. Interpret clearing from the hold type: a plain OUT clears when its enable logic goes false; SET-latched alarms require a reset path, and self-hold circuits require their seal-in path to drop or reset logic to act. Do not infer a power-cycle requirement merely from an empty RST list. Requires the xref DB.
Inputs: root (required), mode, device.
gx3_data_flowA
Build conservative argument-level source-to-destination value-flow edges. Known transfer and other classified instructions produce edges with argument indexes, ranges, widths, execution condition, and confidence. Unknown or partially parsed operations are returned as unresolved records; no guessed edge is emitted. Device comments are included when available.
Inputs: root (required), device, format, opcode.
gx3_dead_logicA
Find logic that can never do anything: contacts that can never close, NC contacts on always-ON relays, coils and words written but never read, and SET latches with no matching RST. Returns findings grouped by kind with the device, its comment and where it appears. Reads the project; WRITES a CSV under the output directory. Devices refreshed from a network are excluded, since a remote station may be the real reader. Requires the xref DB.
Inputs: root (required).
gx3_device_mapA
Report, per device type, observed LD usage, density, and gaps in the index. Gaps are not verified free allocations: ST/FBD, unresolved accesses and external or reserved allocations are not excluded. Verify them in GX Works3 before adding devices. Read-only; returns a table and writes nothing. Requires the index-lite DB: run gx3-cli index-lite build --root <root> once per project first.
Inputs: root (required), types, min_free.
gx3_explain_snapshotA
Match a captured device snapshot against the enable conditions the static trace produced, and say what the snapshot does not answer for. Reads files only: this never opens a PLC connection, and there is no MCP tool that does. Report the analysis state with the result -- a device the snapshot holds no value for comes back as 'no measured value; file only', and the rows that did evaluate are not the whole answer when that appears. One snapshot explains the instant it was captured, never the cause of a past stop or trip: do not use it to answer 'why did this trip earlier'.
Inputs: root (required), device (required), snapshot (required), format, +3 more.
gx3_interlock_checkA
Static satisfiability check: can two coils' ON/enable conditions be true at the same time? A 'mutually-exclusive' verdict is sound; a 'simultaneous-possible' verdict returns a witness assignment but is not a reachability proof.
Inputs: root (required), device_a (required), device_b (required), max_vars, +1 more.
gx3_ladder_printA
Render a program in GX Works3 print-text layout. This is the output to show a user when explaining how a circuit is wired: quote it verbatim in a code block, never a JSON dump of the same rung. Output can be large; pass 'output' to write it to a file. To emit only the circuit under discussion, use 'list_sections' to discover section titles, then filter with 'section', 'pos_range' (A-B), or 'device'.
Inputs: root (required), program (required), device, output, +3 more.
gx3_lintA
Run static review checks over the whole project and return a per-check summary with finding counts by severity. Checks: duplicate coils, multi-writers, alarm quality, unused devices, contradictory comments, linked-device writes, and signed/width/division type problems. Reads the project; WRITES one CSV per check plus a JSON summary into the working directory. Findings are advisory: a duplicate coil may be a deliberate SET/RST pair, so report the severity and let the engineer judge. Needs the index and xref DBs for the full check set.
Inputs: root (required), checks.
gx3_list_commandsA
List every project-read-only GX3 CLI command this server will run, with a one-line summary of each. Read-only; touches no project. Call this before gx3_run_command when no typed tool fits, to see what is actually available rather than guessing a command name.
Inputs: no named parameters.
gx3_network_mapA
Map how this PLC is wired to everything outside it: IP addresses, CC-Link and SCON stations, and safety relationships, aggregated into one view. Use it to find which unit or remote station owns a device before assuming the program drives it. Reads the project and the comm detail CSVs; WRITES its own CSVs under the output directory. It does not communicate with any device -- everything is read from the project files.
Inputs: root (required), prefix.
gx3_replay_captureA
Read an already-captured CSV/JSON device log offline: normalize it, emit per-device time series, list value change points, or export one instant as a snapshot for gx3_explain_snapshot. Reads files only and never opens a PLC connection. An imported or polled log is not a scan-synchronized recording: two devices that appear to change together may simply have been sampled together, so do not read ordering between devices out of it.
Inputs: verb (required), input (required), at, root, +2 more.
gx3_run_commandA
Escape hatch: run any MCP-allowed, project-read-only GX3 CLI command with explicit arguments. Project-mutating commands and local demo generation commands are rejected. Local artifacts are confined to GX3_MCP_OUTPUT_DIR. Prefer the typed tools above when one fits.
Inputs: command (required), args, root, timeout_seconds.
gx3_semantic_diffA
Compare two versions of a project rung by rung and return what was added, removed or changed. Rungs are matched by their stable block GUID rather than by position, so inserting a rung does not report everything after it as changed. Use it to review what a revision actually did. Reads both projects; WRITES a detail CSV. Neither project is modified.
Inputs: new (required), old (required).
gx3_trace_deviceA
Trace a device's ON/OFF/hold conditions from exact ladder topology. MC master-control zone conditions are folded into the enable logic, and the output warns on multi-OUT-coil devices and rows below a conditional jump. The output carries each device's comment: keep every device paired with its comment when you report the result, and show the rung itself with gx3_ladder_print rather than describing it in prose.
Inputs: root (required), device (required), ja, compact, +2 more.
gx3_xref_where_usedA
Writers and readers of a device with POU name and real step. The first line carries the device comment; repeat it alongside the device in your answer instead of reporting a bare device number. Requires the xref DB: run gx3-cli xref build --root <root> once per project first.
Inputs: root (required), device (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Most tools target clearly distinct analysis tasks (interlock check, dead logic, trace, xref, data flow, lint, device map, alarm map, diff, network map, print, snapshot, replay). The main overlaps are gx3_dead_logic vs gx3_lint and the device-relationship cluster of trace_device/xref_where_used/data_flow, but the detailed descriptions provide enough separation to avoid serious misselection.
All names share the gx3_ prefix and snake_case style, which creates a strong family identity. The post-prefix portion mixes verb-led names (trace_device, explain_snapshot, replay_capture, run_command) with noun-led report names (dead_logic, device_map, alarm_map, semantic_diff, network_map, ladder_print), a mild convention split that is still readable and predictable.
At 15 tools, the count is at the upper boundary of the well-scoped range, and each tool earns its place by addressing a distinct analysis workflow. The command-discovery and escape-hatch tools (gx3_list_commands, gx3_run_command) are justified additions rather than padding for this domain.
The server covers the core static-analysis, comparison, printing, and offline-capture workflows comprehensively. Minor gaps exist: gx3_ladder_print references a list_sections tool that is not provided as a typed tool, and prerequisite xref/index DBs must be built outside the server, but gx3_run_command or user instructions can work around these.
Maintenance
Related MCP Connectors
Cloud renderer: TIA Portal SimaticML (FC/FB/OB, LAD or SCL) into PNG ladder diagrams over MCP.
Generate TIA Portal importable SimaticML (V19) from LadDoc IR, with strict validation, over MCP.
2,000+ MCP servers read at source level. Know what one does before you connect. Free, no key.
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI agents to read and understand local Mendix project structure and logic by connecting directly to the .mpr file via MCP. Allows querying microflows, entities, attributes, and modules in read-only mode without requiring cloud access.41ISC
- FlicenseAqualityDmaintenanceAn MCP server for ABB/Hitachi Energy PCM600 that provides offline IEC 61850 SCL file analysis, .apcmp project archive inspection, ACT logic recovery, and safe read-only drive of the PCM600 CLI for project exports and validation.231-
- AlicenseBqualityBmaintenanceEnables MCP-compatible agents to perform read-only inspection of OpenPLC Editor projects, including retrieving project structure and listing programs, function blocks, and functions.3Apache 2.0
- FlicenseAqualityCmaintenanceLets AI agents and users analyze Mitsubishi MELSEC .gx3 projects directly, tracing coil conditions, checking device references, comparing program changes, and inspecting ladder logic without opening GX Works3.134-