gx3-cli-mcp

Local GX Works3 project analysis for engineers and AI agents.

gx3-cli-mcp provides a Windows-first CLI and stdio MCP server for inspecting GX Works3 (.gx3) projects on your own machine. It helps you search devices, comments, cross references, ladder conditions, communication boundaries, and static review signals without modifying the source project.

日本語: GX Works3 (.gx3) プロジェクトをローカルで読み取り解析し、AI エージェントからも使える CLI / MCP サーバーです。プロジェクトを書き換えず、 デバイス、コメント、xref、ラダー根拠、通信境界を確認するための道具です。

This is an unofficial, independent tool. It is not endorsed by Mitsubishi Electric.

What You Can Do

• Find where a device is used and whether it is read, written, or referenced.

• Search device comments such as start, stop, alarm, cycle, step, or manual operation keywords.

• Trace upstream conditions for a coil and print nearby ladder evidence.

• Build xref and SQLite indexes so AI agents can answer from structured facts.

• Review static risks such as duplicate coils, multi-writers, dead logic, and interlock possibilities.

• Inspect external inputs, HMI/communication boundaries, IP maps, link maps, timing candidates, and project-wide summaries.

Related MCP server: TwinCAT Validator MCP Server

What It Does Not Do

• It does not include real customer or production PLC projects.

• It does not send project data to an online service by itself.

• It does not provide a GUI in this release.

• It does not require a license token or paid-plan token.

• The MCP server does not expose project-mutating commands.

Install

python -m pip install git+https://github.com/purinzan/gx3-cli-mcp.git
gx3-cli --version
gx3-mcp-server --version

For local source checkout:

python -m pip install -e .

First Analysis

Run these three commands first for a real project:

gx3-cli doctor --root C:\path\to\project.gx3
gx3-cli index-lite build --root C:\path\to\project.gx3
gx3-cli xref build --root C:\path\to\project.gx3

Then inspect a device:

gx3-cli query-device M100 --root C:\path\to\project.gx3
gx3-cli xref where-used M100 --root C:\path\to\project.gx3
gx3-cli trace-device M100 --root C:\path\to\project.gx3 --strict-logic --compact

When you pass a .gx3 file, the tool extracts it into .gx3_cache\<sha256>\ and analyzes that local cache.

Common Tasks

Use the indexed commands above for normal lookup and discovery. Avoid starting AI workflows with raw text search over extracted GX3 files; GX Works3 projects contain binary/database files, and the CLI preserves device, comment, POU, role, and step context.

Use With MCP

The MCP server is intended for AI clients that support stdio MCP servers.

{
  "mcpServers": {
    "gx3": {
      "command": "python",
      "args": ["-m", "gx3cli.gx3_mcp_server"]
    }
  }
}

If your client can resolve console scripts from PATH:

{
  "mcpServers": {
    "gx3": {
      "command": "gx3-mcp-server"
    }
  }
}

The MCP server exposes read-only analysis tools and a restricted command runner. Synthetic demo generation is local CLI-only.

Demo Project

Use a synthetic project for screenshots, tutorials, and first-time tests.

gx3-cli synthetic-project demo.gx3 --overwrite
gx3-cli doctor --root demo.gx3
gx3-cli trace-device M100 --root demo.gx3 --strict-logic --compact

Data And Safety

• Project files stay on your machine unless you pass outputs to another tool.

• Some commands create local files such as SQLite indexes, CSV reports, ZIP support bundles, or Markdown summaries.

• Analysis output is advisory. Verify findings in GX Works3 and through your own safety/quality process before changing real equipment.

• The tool is not a substitute for PLC validation, machine safety review, or official engineering software.

Documentation

Recommended reading:

1. User manual (JA): Japanese install and usage guide.

2. Agent usage guide (JA): how AI agents should use the indexed tools.

3. Security note (JA): local data handling and read-only MCP policy.

4. Validation matrix (JA): verified scope and limitations.

5. File usage guide (JA): repository file map for agents and contributors.

MCP configuration examples:

• MCP client config: robust python -m gx3cli.gx3_mcp_server launch.

• MCP client config, console script: direct gx3-mcp-server launch when PATH is reliable.

Distribution terms are defined in LICENSE.txt.

For Contributors

Before changing or publishing this project, run the same checks used by CI:

python run_tests.py
python scripts\release_gate.py .
python -m build --wheel
python scripts\release_gate.py dist\gx3_cli_mcp-*.whl