Skip to main content
Glama
gx3-mcp-server

gx3-mcp-server

gx3-cli-mcp

日本語 · English · 简体中文 · 한국어

PyPI Python CI License gx3-cli-mcp MCP server

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-mcp

Python 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.gx3

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

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 next

Then 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.gx3

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/<sha256>/ 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

{
  "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

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.

gx3-mcp-server on Glama

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 tools
gx3_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

    A4.2/5.0

    Scored across 15 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables 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.
      4
      1
      ISC
    • F
      license
      A
      quality
      D
      maintenance
      An 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.
      23
      1
      -
    • F
      license
      A
      quality
      C
      maintenance
      Lets 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.
      13
      4
      -