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.

---

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:

DM	Function	Default
D0	Schedule 1 — hour	6
D1	Schedule 1 — minute	0
D2	Schedule 2 — hour	16
D3	Schedule 2 — minute	0
D4	Run duration x100ms	300 (=30s)

Changes take effect immediately without PLC restart.

---

Run Tests

uv run pytest -q

Available MCP Tools

Tool	Description
load_project	Load a .cxp or .cxt file into a session
list_programs	List all programs in the project
list_sections	List sections in a program
get_program_context	Get full ladder content of a program
get_rungs	Get rungs in a section
replace_rung	Replace a rung's instructions
insert_rung	Insert a new rung
delete_rung	Delete a rung
set_rung_comment	Set a rung comment
patch_program	Batch multiple rung edits atomically
create_section	Add a new section
rename_section	Rename an existing section
upsert_symbol	Add or update a symbol
clear_symbols	Clear all symbols in a scope
list_symbols	List all symbols
validate_program	Validate XML structure
save_cxt	Save as .cxt
save_cxp	Re-encode and save as .cxp
list_project_templates	List available built-in templates
create_project_from_template	Create a new blank project from template
compile_rung	Validate mnemonic instructions
simulate_rung	Boolean simulation of a rung
analyze_rung	Analyze rung structure
program_diagnostics	Full program diagnostics
semantic_snapshot	Semantic JSON snapshot for AI review
launch_in_cx_programmer	Save and open in CX-Programmer (Windows)

---

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).