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., "@Sysmac Studio File Editor MCP Compare my two local .smc2 project copies and list variable and POU differences"
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.
An offline-first Model Context Protocol (MCP) server for inspecting, comparing, and transactionally editing local copies of Omron Sysmac Studio projects.
The project is experimental and source-available under the PolyForm Noncommercial License 1.0.0. It is not an Omron product and is not affiliated with or endorsed by Omron.
Safety and privacy: The server does not connect to a PLC, download a program, or force I/O. Work on an authorized copy, review every proposed change, and rebuild the exported candidate in Sysmac Studio before relying on it. A successful build does not verify machine behavior or wiring. Project names, source, and tool results may be sent to the model provider by your MCP client; use only data you are authorized to share and follow your organization's data-handling rules.
Inspects .smc2 archives and reports observed project members.
Reads and compares project copies, with structural comparison of observed variables, POU, tasks, DataTypes, hardware, and I/O.
Stages supported offline edits to ST/LD sections, variables, POU, task assignments, I/O bindings, and selected DataTypes.
Uses transactions with expected revisions, previews, partial validation, commit to a local working copy, rollback, and export to a new path.
Generates and imports a bounded subset of PLCopen IEC XML for ST, Ladder, globals, and selected DataTypes.
Optionally communicates with a locally installed Sysmac Studio through typed Windows-only operations, including open-copy, runtime status, rebuild, and guarded export.
This is not a full IEC 61131-3 parser, compiler, or semantic checker. Unsupported or incomplete structures are reported as limitations.
Related MCP server: plc-ai-agent
Python 3.11 or newer.
An MCP client that supports the local stdio transport.
No Sysmac Studio installation, cloud account, API key, or listening network port is required for the core archive and transaction workflows.
Windows is the primary development and validation platform. The Python core may run in other environments with compatible Python dependencies, but Linux, macOS, and WSL are not currently part of the tested support matrix.
Windows x64 and Sysmac Studio installed locally.
The vendor contract assemblies and .NET Framework compiler supplied by the local installation, to build the WCF client.
A local Node.js executable and the verified Frida 17.23.2 package, to create the hash-pinned runtime profile used by runtime operations.
User approval of the normal Windows UAC prompt for operations that require elevation.
The optional Windows integration depends on the local Sysmac Studio release. The repository does not include Omron binaries. The integration is experimental and must be validated against the exact IDE version and an authorized demonstration project.
Building the Windows x64 helper requires the .NET SDK version pinned in bridge/SysmacFormats/global.json (currently 10.0.403) and NuGet package restore. It is not needed for the basic MCP server.
Clone the repository and create a virtual environment from the project root:
git clone https://github.com/il-prof-f-a/sysmacstudio-file-editor-mcp.git
cd sysmacstudio-file-editor-mcp
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e .For development and tests, install the optional development dependencies:
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"The server communicates with its MCP client over standard input/output. It does not open a listening TCP port.
Add an entry like this to the MCP client's configuration, replacing both paths with absolute paths on your machine:
{
"mcpServers": {
"sysmacstudio": {
"command": "C:/path/to/sysmacstudio-file-editor-mcp/.venv/Scripts/python.exe",
"args": [
"-m",
"sysmac_mcp",
"--workspace",
"C:/path/to/sysmacstudio-file-editor-mcp/workspace"
]
}
}
}See mcp-config.example.json for the optional IDE environment variables. The supplied sample contains placeholders and must be adapted locally. Do not commit a local configuration, runtime profile, project archive, or receipt.
You can also start the server manually:
.\.venv\Scripts\python.exe -m sysmac_mcp --workspace .\workspaceThe read-only command-line reports are:
.\.venv\Scripts\python.exe -m sysmac_mcp inspect 'C:\path\to\project.smc2'
.\.venv\Scripts\python.exe -m sysmac_mcp compare 'C:\path\to\before.smc2' 'C:\path\to\after.smc2'
.\.venv\Scripts\python.exe -m sysmac_mcp compare-projects 'C:\path\to\before.smc2' 'C:\path\to\after.smc2'Read plc_get_capabilities, then open an authorized project copy with plc_open_project.
Inspect the relevant variables, POU, sections, tasks, hardware, and references.
Start a transaction with plc_begin_transaction, passing the revision returned by the project read.
Preview with plc_preview_changes and run plc_validate. Review every changed archive member.
Commit to the MCP-managed local copy with plc_commit_changes, or discard the staged changes with plc_rollback.
Export to a new path with plc_export_project. Treat the output as a candidate until Sysmac Studio imports and rebuilds it.
The local IDE tools are separate from archive editing. They use explicit, typed operations and do not expose arbitrary WCF method calls. plc_ide_rebuild_active rebuilds the active offline solution; it does not download to a controller. plc_ide_export_active uses the native IDE export path with identity, destination, save, and session checks. Both require the optional Windows integration and its UAC flow.
Project snapshots, transactions, IDE jobs, receipts, and runtime profiles belong in local ignored folders such as workspace/.
Do not add .smc/.smc2 archives, extracted project data, IDE logs, runtime profiles, receipts, or customer identifiers to the repository or an issue.
.gitignore helps prevent accidental additions, but does not remove files already tracked or erase Git history. Review the staged file list before committing.
The server uses local stdio; your MCP client and model provider may process tool output separately. Choose a client and model approved for the project data you use.
Bug reports and feature suggestions are welcome through GitHub Issues. Questions and design discussion can go to GitHub Discussions. Read CONTRIBUTING.md before opening a pull request. Never attach a real customer project or unsanitized diagnostic output.
For security concerns, follow SECURITY.md and do not publish exploit details in an issue.
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check src tests
.\.venv\Scripts\python.exe -m buildOriginal project material is licensed under the PolyForm Noncommercial License 1.0.0. Its terms allow only the purposes defined by that license; a separate permission from the relevant rights holder is required for uses outside those terms. This is a source-available, noncommercial project, not OSI-approved open source: the Open Source Definition does not permit licenses to restrict fields of endeavor such as business use (OSI definition).
Runtime dependencies are listed in pyproject.toml and remain under their respective upstream licenses. The license summary above is informational; the complete terms in LICENSE govern.
Resolve one declaration's observed ST/LD references by scope, external aliases and known members/parameters. Return paginated references, diagnostics and explicit incomplete coverage; no full type checker or HMI/library analysis.
Inputs: project_id (required), variable_id (required), limit, offset, +1 more. Returns: object
Assign, move or reorder one Program in an existing task. Position is one-based; omitted preserves the current position or appends a new assignment. Startup omitted preserves an existing setting, or enables a new assignment. Atomically update task XML and OEM links; reject inconsistent identities, ambiguous instances and cross-controller moves. No PLC or Sysmac build implied.
Inputs: task_id (required), program_id (required), transaction_id (required), expected_revision (required), +2 more. Returns: object
Begin persistent staging against the current project revision; original files remain untouched.
Inputs: project_id (required). Returns: object
Stage a binding to an originally observed address or enabled configured port resolved by an exact local profile. Reject occupied, incompatible and known overlapping output aliases.
Inputs: address (required), variable_id (required), transaction_id (required), expected_revision (required). Returns: object
Commit staging to a new local revision. This does not apply changes in Sysmac Studio or compile PLC code.
Inputs: transaction_id (required). Returns: object
Compare hashes and ZIP member content; this does not prove PLC semantic equivalence.
Inputs: after (required), before (required). Returns: object
Compare two local SMC2 copies by observed objects, variables, ST/LD and tasks, retaining every ZIP member delta. Return bounded fingerprints and paginated model/archive differences. Logical paths match objects across ID changes; ambiguous matches and unacquired content are explicit. This does not prove functional equivalence, successful build or IDE round-trip.
Inputs: after (required), before (required), limit, offset. Returns: object
Stage a new POU from a readable single-section template in the same controller/folder. Infer Program/Function/FB and ST/LD from the template; provide fresh declarations and exactly one ST source or native LD rungs. Add fresh IDs and models atomically without copying application code/build caches. Result remains unverified until Sysmac rebuild.
Inputs: definition (required), transaction_id (required), template_pou_id (required), expected_revision (required). Returns: object
Stage a declaration in an existing global or local VAR group. Case-insensitive collisions are rejected.
Inputs: name (required), table_id (required), data_type (required), transaction_id (required), +2 more. Returns: object
Stage deletion of one unreferenced top-level leaf DataType. Requires an exactly observed controller table, matching listed name/BaseType, complete controller source and no references in declarations, source, or other DataTypes. Nested members, libraries, external consumers, and Sysmac build are not covered; the archive member and original project remain preserved until commit/export.
Inputs: data_type_id (required), expected_name (required), transaction_id (required), expected_revision (required), +1 more. Returns: object
Stage removal of one POU from the OEM project tree. Refuses assigned Programs, observed source/declaration references and incomplete controller source or DataTypes; archive members are preserved as unreferenced data. External consumers are not acquired, and Sysmac rebuild is required before use.
Inputs: pou_id (required), transaction_id (required), expected_revision (required). Returns: object
Stage removal of one variable only when its observed declarations and source are safe. Refuses read-only or I/O-bound variables, observed code/declaration references, incomplete source, and global declarations with VAR_EXTERNAL aliases. External consumers are not acquired; no Sysmac build is implied.
Inputs: variable_id (required), transaction_id (required), expected_revision (required). Returns: object
Write an unverified SMC2 candidate to a new path; never overwrite the original or another file.
Inputs: project_id (required), destination (required). Returns: object
Find lexical ST/LD references excluding comments/strings. Does not resolve scope or external HMI dependencies.
Inputs: symbol (required), project_id (required), limit, offset. Returns: object
Generate IEC 61131-10 ST or basic Ladder POUs and variables for import. Validate against a local XSD when available; never imply IDE import/build.
Inputs: name (required), pous (required), destination (required), global_variables (required), +1 more. Returns: object
Report implemented adapters, experimental formats and unavailable Sysmac operations.
Inputs: no named parameters. Returns: object
Read controller metadata, object counts and explicit unknown coverage for an opened project.
Inputs: project_id (required). Returns: object
Close only the expected active normal imported Sysmac solution. Requires normal Windows UAC, the same process-start and solution identities, a completed native editor flush, and a clean model. Refuses file mode, AutoConnect, save suppression, dirty state, importing, or changed context. Uses the normal UserCloseSolution command once and requires matching close events plus a later empty-solution snapshot; never answers save prompts. Timeout remains unknown without retry. Does not save, export, compile, import, or operate a PLC.
Inputs: process_id (required), solution_id (required), process_started_utc (required). Returns: object
Save and export the attested active normal imported solution through the pinned Sysmac runtime. Provide process identity from runtime_status and the solution GUID/storage_folder from list_projects. Destination must be a new local SMC2 path outside the persistence folder and on the same drive. The export uses native command rules and may show a normal Sysmac prompt; it refuses file mode, AutoConnect, changed identities, suppressed saves, persistence IO errors, and existing output paths. Publishes only a readable SMC2 copy; no PLC connection or download.
Inputs: process_id (required), destination (required), solution_id (required), storage_folder (required), +1 more. Returns: object
Read a bounded page of persisted projects in the local Sysmac IDE through the pinned runtime adapter and normal UAC. Returns solution GUIDs and process start identity for open_existing, including from the start page. Does not import, open, save or compile a project; storage folders are IDE locations, not source archive paths.
Inputs: process_id (required), limit, offset. Returns: object
Prepare a verified copy of the committed revision and open it in the configured Sysmac WCF host. Requires Windows UAC. Return actual OpenFromFile callback; duplicate projects remain refused, without overwrite/delete. Does not compile.
Inputs: project_id (required), expected_revision (required). Returns: object
Open one persisted Sysmac project by the GUID returned by list_projects. Requires normal UAC, the same process start and an idle empty start page. Preserves vendor permission/availability checks and requires matching completion event plus final solution identity. Does not close another project, import/overwrite/delete, save, compile or operate a PLC. Timeout remains unknown without automatic retry.
Inputs: process_id (required), solution_id (required), process_started_utc (required). Returns: object
Check the local Sysmac WCF endpoint with the direct non-elevated probe. No project is opened or compiled, and no UAC prompt is required.
Inputs: no named parameters. Returns: object
Rebuild the active offline NX controller only if the process start, solution and controller identities still match runtime_status. Requires UAC. Return correlated completion, native result and compiler diagnostics; timeout is unknown and never retried. Does not import, save or connect to a PLC.
Inputs: process_id (required), solution_id (required), controller_id (required), process_started_utc (required). Returns: object
Read the active local Sysmac solution/controller identities, rebuild availability and file-mode state through the pinned runtime adapter. Requires normal Windows UAC and explicit Sysmac PID; does not save, export or compile. Use its process start identity and GUIDs for rebuild.
Inputs: process_id (required). Returns: object
Inspect a local file without modifying it; return digest and bounded container summary.
Inputs: path (required). Returns: object
List observed native DataType definitions or a type's direct members. IDs use the entity ID and XML path, not a vendor GUID; table provenance and partial coverage are returned.
Inputs: project_id (required), limit, offset, parent_id, +2 more. Returns: items, total, tables, next_offset, +4 more
List configured NX, built-in and EtherCAT modules using exact local profiles. Configuration is not physical verification; coverage remains partial.
Inputs: project_id (required), limit, offset, transaction_id. Returns: object
Read declared variable-to-address bindings. These are observed bindings, not a complete hardware inventory.
Inputs: project_id (required), limit, offset. Returns: object
List configured or observed ports, types, addresses and bindings. Available means resolved, enabled and unoccupied, including known output aliases; it does not imply hardware/build verification.
Inputs: project_id (required), limit, offset, direction, +3 more. Returns: object
List programs, functions and function blocks. Use returned IDs for reads and edits.
Inputs: project_id (required), limit, offset, transaction_id. Returns: object
Read task metadata and associated programs from the project.
Inputs: project_id (required), limit, offset, transaction_id. Returns: object
List global or POU-local declarations and preserved attributes. Scope is 'global' or a POU ID.
Inputs: project_id (required), limit, query, scope, +2 more. Returns: object
Acquire a native SMC2 into immutable local storage. Return project ID, revision and coverage.
Inputs: path (required). Returns: object
Prepare a concrete native variable rename without staging. Check aliases, scope collisions, unavailable source and reference capture by rebinding; paginate proven references and report blockers. External consumers and Sysmac build remain unverified.
Inputs: new_name (required), project_id (required), variable_id (required), limit, +2 more. Returns: object
Prepare a guarded rename of one top-level controller DataType without staging. Scan observed declarations, native DataType expressions, and typed ST/Ladder literals; report collisions and unsupported references. Libraries, external consumers, other controllers, and Sysmac build remain unverified.
Inputs: new_name (required), project_id (required), data_type_id (required), expected_name (required), +4 more. Returns: object
Read staged operations and changed archive members before committing.
Inputs: transaction_id (required). Returns: object
Preview PLCopen ST POUs, simple global variables, structures, unions, named DINT enumerations, fixed one-dimensional array aliases, nested DataType namespaces, and up to 1000 ordered LD rungs. Array aliases are expanded inline in variable and structure member types; they are not registered as named native DataTypes. Structures use Sysmac's automatic NJ member layout. PLCopen DataType namespaces are flattened into the selected native table's flat symbol scope; references to imported namespaced types are rewritten, and duplicate names after flattening are rejected. Each rung must be linear or have one two-path split/join, NO/NC contacts, and one standard final coil; multi-rung files require unique explicit evaluationOrder values. Nested branches, negated coils, complex LD, variable-length/multidimensional arrays, structured initial values, namespaced POUs, and namespace comments remain blocked. New data types must fit completely observed native DataType tables; pass data_type_table_id when the project has multiple tables. All edits stay in the local transaction; no staging or Sysmac action occurs.
Inputs: xml_path (required), transaction_id (required), template_pou_ids (required), expected_revision (required), +2 more. Returns: object
Read POU metadata and section IDs; fetch source with plc_read_section to bound response size.
Inputs: pou_id (required), project_id (required), transaction_id. Returns: object
Read source lines or native Ladder rungs, optionally from staged transaction state.
Inputs: project_id (required), section_id (required), limit, offset, +1 more. Returns: object
Register an existing same-controller global as VAR_EXTERNAL in one POU. Preserve source, reject local name/type conflicts and avoid duplicate aliases. Useful for repairing missing declarations reported by plc_validate.
Inputs: pou_id (required), transaction_id (required), expected_revision (required), global_variable_id (required). Returns: object
Stage a guarded rename of one top-level controller DataType and its observed typed references. Read plc_plan_rename_data_type first. Unsupported expressions, collisions, incomplete controller tables, and uncertain Ladder fields are rejected. No external-consumer update or Sysmac build is implied.
Inputs: new_name (required), data_type_id (required), expected_name (required), transaction_id (required), +2 more. Returns: object
Recompute and stage a guarded variable rename atomically across declarations, ST and LD. Read plc_plan_rename first. Return the new variable ID; reject incomplete affected source, collisions or reference capture. No IDE build or external-consumer updates are implied.
Inputs: new_name (required), variable_id (required), transaction_id (required), expected_revision (required). Returns: object
Discard an active transaction. Committed revisions are not overwritten.
Inputs: transaction_id (required). Returns: object
Stage a previously previewed PLCopen ST/linear-LD import with simple global variables and supported structures, unions, named DINT enumerations, fixed one-dimensional array aliases, and nested DataType namespaces flattened into the selected native table's flat symbol scope. Array aliases are expanded inline in variable and structure member types; they are not registered as named native DataTypes. Structures use Sysmac's automatic NJ member layout. Qualified references to imported types are rewritten and duplicate names after flattening are rejected. Pass the same DataType table entity ID used in preview when the project has multiple tables. Unsupported namespaced POUs, namespace comments, nested/complex LD, variable-length or multidimensional arrays, and structured initial values remain blocked. Source hash, table selection, plan, templates, project revision and staged snapshot must still match; commit and IDE build remain separate.
Inputs: xml_path (required), transaction_id (required), expected_plan_id (required), template_pou_ids (required), +4 more. Returns: object
Stage removal of one Program assignment from the selected task. Refuses ambiguous or inconsistent task models and preserves the now-unreferenced association model file in the archive. The Program itself and its source remain unchanged; the result is unverified until Sysmac rebuild.
Inputs: task_id (required), program_id (required), transaction_id (required), expected_revision (required). Returns: object
Stage removal of a global variable hardware address; can be paired with bind_io in the same transaction.
Inputs: variable_id (required), transaction_id (required), expected_revision (required). Returns: object
Stage native Ladder rung objects and register newly introduced known global dependencies as VAR_EXTERNAL. Read original rungs first and preserve unknown fields.
Inputs: rungs (required), section_id (required), transaction_id (required), expected_revision (required). Returns: object
Stage one ST body and register newly introduced known global dependencies as VAR_EXTERNAL. Syntax/type checking and Sysmac compilation are not implied.
Inputs: source (required), section_id (required), transaction_id (required), expected_revision (required). Returns: object
Stage data_type, initial_value, retained or comment fields. Unbind before changing a bound variable type. Use plc_rename_variable for renames and bind_io/unbind_io for addresses.
Inputs: changes (required), variable_id (required), transaction_id (required), expected_revision (required). Returns: object
Validate staged models with bounded ST lexer/delimiter and scalar checks, built-in integer literal range checks, and missing VAR_EXTERNAL reports. Check complete native DataType tables for empty STRUCTs and missing explicit byte offsets in OffsetType=User structures; BOOL members also require a bit offset. Automatic NJ/CJ offsets are not diagnosed. Scan Ladder for unsupported instructions. Function calls, members, arrays, enums, unions, references, library types, full ST grammar, Ladder semantics, DataType layout calculation, and Sysmac build remain outside this partial analysis; coverage is returned explicitly.
Inputs: transaction_id (required). Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 51 tools
The toolset is large but carefully partitioned: plc_ide_* tools cover live Sysmac IDE automation, while the remaining tools cover offline SMC2 project editing and transactions. Overlaps such as open_project vs. ide_open_existing/ide_open_copy and export_project vs. ide_export_active are explicitly differentiated, though the number of near-neighbor tools raises some misselection risk.
All tools use snake_case with a consistent plc_ prefix and verb_noun structure. The ide, transaction, import, and rename families are predictable, and minor variants like get_project_info or analyze_symbol do not break the convention.
At 51 tools, the surface is far beyond the practical 3-15 range and is likely to overwhelm an agent during tool selection. The operations are well-organized and largely non-redundant, which keeps it from being chaotic, but the count is still excessive.
Coverage is strong: project open/export, transaction staging/commit/rollback, POU and variable CRUD, references, validation, IEC XML import/export, and IDE open/close/rebuild/runtime status are all present. Minor gaps remain around direct create/update DataType operations and task lifecycle beyond assign/unassign.
Manage SysML2 projects; check, evaluate, verify, query, document and diagram models.
Change-impact intelligence for tracing dependencies, stale references and required updates.
Independent static checks for supported tag and alarm CSV import formats; no HMI or PLC access.
Cloud PLC simulator: validate and step-run LAD/SCL programs, run scenarios, return PASS/FAIL.
