cx-programmer-mcp

An MCP (Model Context Protocol) server for editing OMRON CX-Programmer ladder logic programs programmatically — without opening the GUI.

Works with .CXP / .CXT files for OMRON CJ/CP/CS series PLCs.

Scope: Programs, Sections, Ladder Mnemonics, rung comments, and symbol table only.
Does not touch PLC Setup, I/O Table, network configuration, passwords, or transfer to PLC.

How it works

OMRON documents .CXP as a compressed version of .CXT. .CXT is a text-based format that CX-Programmer can import/export. This server reads .CXP or .CXT, edits the program in memory, then saves the result as .CXT / .CXP for review in CX-Programmer before deploying to a real PLC.

Uses Python MCP SDK v2 (MCPServer) with stdio transport.

Related MCP server: TwinCAT Validator MCP Server

Requirements

• Python >= 3.10

• uv package manager

• CX-Programmer installed (to open .cxp output and download to PLC)

Installation

cd cx-programmer-mcp
uv sync
uv run cx-programmer-mcp

Project Template Setup

Built-in template (CJ2M CPU11)

A native CJ2M CPU11 template is included. Generate a blank project:

uv run python make_template.py

Other PLC models

Each PLC model has a different binary configuration. For models other than CJ2M CPU11:

1. Open CX-Programmer on your machine

2. Create a new empty project for your PLC model (CP1L, CS1G, etc.)

3. Save it as .CXP or .CXT

4. Place the file in the project/ folder

5. Update make_template.py to point to your file:

SRC = Path(__file__).parent / "project" / "your_blank_template.cxp"

6. Run make_template.py once

Example Program

An example ladder program is included: project/example_basic_io.cxp

It demonstrates a simple conveyor/IO controller with:

• Manual output control (hold-to-run)

• Scheduled auto run via RTC (configurable via DM)

• Timer-based duration

• SET/RSET latch

• Emergency reset

To rebuild it from source:

uv run python make_template.py
uv run python build_program.py

Output: project/example_basic_io.cxp — open in CX-Programmer to review and download.

Review Program

uv run python review_program.py

MCP Client Configuration

Add to your MCP client config (Claude Desktop, Kiro, Cline, etc.):

{
  "mcpServers": {
    "cx-programmer": {
      "command": "uv",
      "args": ["run", "cx-programmer-mcp"],
      "cwd": "ABSOLUTE_PATH_TO_THIS_FOLDER"
    }
  }
}

Windows example:

"cwd": "C:\\Users\\yourname\\cx-programmer-mcp"

Optional — restrict file access to specific folders:

CX_MCP_ALLOWED_ROOTS=C:\PLC_Projects

Runtime Schedule Changes

Use CX-Programmer Online Mode → PLC Memory → DM Area:

Changes take effect immediately without PLC restart.

Run Tests

uv run pytest -q

Available MCP Tools

Project Structure

cx-programmer-mcp/
├── src/cx_programmer_mcp/     # MCP server and CXT library
│   ├── server.py              # MCP tool definitions
│   ├── cxt.py                 # CXT/CXP parser and editor
│   ├── ladder.py              # Mnemonic compiler and simulator
│   ├── diagnostics.py         # Program diagnostics
│   ├── recipes.py             # Reusable ladder patterns
│   ├── templates/             # Built-in PLC templates
│   │   └── CJ2M_CPU11.cxt     # Native CJ2M CPU11 template
│   └── ...
├── tests/                     # Test suite (16 tests)
├── project/                   # Output folder
│   └── example_basic_io.cxp   # Example ladder program
├── build_program.py           # Builds the example ladder program
├── write_build.py             # Regenerates build_program.py
├── make_template.py           # Generates blank template from base
├── review_program.py          # Prints program content to console
└── pyproject.toml

Notes

• Always run Program Check in CX-Programmer before downloading to a real PLC.

• This tool edits program logic only — I/O table, unit setup, and PLC configuration are preserved as-is from the template.

• .CXP output is binary-compatible with CX-Programmer 9.73 on CJ2M CPU11.

• For other PLC models, provide your own blank .CXP template (see Project Template Setup).