Command line, MCP server and plugins
Projects and the parts server without a window, for scripts and AI agents.
openecraft-cli edits projects and maintains the parts server without a window. The same
commands are offered to AI agents over the Model Context Protocol
(openecraft-cli mcp, JSON-RPC on stdin / stdout), so an agent can create projects, place
symbols, draw wires between connection points, assign parts, run the check, generate
reports and export PDF / SVG / DXF / DWG.
cargo run --release -p openecraft-cli -- help # all commands
cargo run --release -p openecraft-cli -- help connect # parameters of a command
cargo run --release -p openecraft-cli -- --version # also -V or version
openecraft-cli new_project --name "Pump control" --path pump.oec
openecraft-cli new_project --example star_delta_starter --path star_delta.oec # see list_examples
openecraft-cli -p pump.oec place_symbol --page 1 --symbol pb_no --x 200 --y 100 # -S1
openecraft-cli -p pump.oec place_symbol --page 1 --symbol coil --x 200 --y 160 # -K1
openecraft-cli -p pump.oec place_part --page 1 --part GEN.LMP-GN-24 --x 240 --y 160 # -P1 with its part
openecraft-cli -p pump.oec connect --page 1 --from -S1:14 --to -K1:A1
openecraft-cli -p pump.oec check
openecraft-cli -p pump.oec export --format pdf --path pump.pdf
openecraft-cli --server http://127.0.0.1:8090 --token <secret> parts_import --path parts.csv
openecraft-cli --server http://127.0.0.1:8090 --token <secret> parts_import --path 6ED1052-1CC08-0BA3.edz
openecraft-cli --project drawing.oec import_eplan_symbols --path drive.edz
openecraft-cli --project drawing.oec import_eplan_symbols --path Beckhoff --part BEC.EK1100
-
On the command line every change is written back to
--projectat once. In an MCP session the project stays open in memory:save_projectwrites it,undo/redorevert single tool calls (help mcp); the command line refusesundo/redo, as it opens the project anew for every command. An archive given as--projectstays unchanged: save the project as a project file (save_project --path <file>.oec) or convert the archive (convert_project). -
A split project keeps the project as many small files for version control (git): the index
<name>.oecpwith a folderpages(one file per page),data(one file per device, part, cable … and per area of the project-wide data; the files of a kind are spread over 16 folders, so that none grows too large) andfiles(embedded documents and images as plain files) next to it. It holds the same project as the.oecfile:convert_project --path plant.oec --format oecpwritesplant/plant.oecp,--format oecor--format oeczconvert back, and--project plant/plant.oecpworks on it like on a project file – a change rewrites only the files it concerns. Every file is one line of JSON and depends only on the content of the project, so saving an unchanged project changes nothing. A split project needs a folder of its own; other files in it (a README,.gitattributes) are left alone. A folder that has no index but already holds JSON files inpages,dataorfilesis refused: they are someone else's and would be replaced or removed. -
Saving a large split project costs what changed, not what the project holds: only the pages and data that differ from the last save are written (a project of 500 pages and 20 000 devices saves a changed page in well under a second). A save is one step: the changed files are written next to the old ones, a journal (
.oecp-save) names them, and only then they take their places; after a crash the project is as it was before the save, or the next access finishes it. -
Git needs two things for a split project. The
.gitattributesthat saving writes into the folder (unless there is one) keeps git from converting line ends, which would change every file and damage the embedded ones; a.gitignorewritten with it leaves out the journal and the temporary files of a save in progress. And the merge driver merges the JSON files record by record, so that changes to different symbols of a page, or to different fields of one, do not conflict; set it up once per clone:git config merge.openecraft.name "OpenECraft split project" git config merge.openecraft.driver "openecraft-cli merge_project_file --base %O --ours %A --theirs %B --name %P"Where both sides changed the same value, the file keeps the value of the current branch, the command names the places and git marks the file as conflicted: open the project, set what is right and
git addthe file. Without the driver git merges the files as text and writes both versions into them; such a file is named when the project is opened: take one version (git checkout --oursor--theirs) and set up the driver. -
Ids of new objects. Every copy of a split project starts the ids of its new objects at a random place above the ids in use, so that two people who add objects on their branches do not give them the same ids (ids therefore grow in steps, by up to 67 million per editing session that adds objects). This is a safeguard with limits, not a guarantee:
- The chance of about 1 in 30 000 for two copies edited at the same time holds while each adds fewer than 1 024 objects. A session that imports a large macro or copies many pages spans many of the places ids start at: two copies that each add about 50 000 objects meet roughly 1 time in 650.
openecraft-cli -p plant/plant.oecp check_project_datareports ids used more than once and--repairrenumbers them: run it after a merge. A reference to such an id (a connection to an object) cannot tell which of the two objects it meant and may end up on the wrong one, so look at what the repair names.- Only the session that edits a project starts its ids anew; reading one (the comparison, a template, the project database) does not, and a project made from a template counts on.
-
Changes of another program while the project is open (a
git pull, a second editor): saving writes only the files this side changed and keeps the others; the editor and an MCP session then read the project again, so that it shows both. A file changed on both sides is not overwritten: the save fails and names the files. Save under another name, or open the project again and repeat the changes. The editor keeps the undo steps (undo does not take back what the other program changed) and remembers the files between runs, so a pull made while it was closed is treated the same way. -
Parameters are
--name value(also--name=value, or all at once with--json '{…}'); lists as--ids 3,4and points as--points "0,0 40,0"; lists of codes, tags or languages are separated by commas or blanks. Values outside their range are refused with the allowed range, not clamped, and a command that fails leaves the project unchanged. Numbers in answers are rounded to the precision they are stored with. -
Parameters renamed since earlier versions are still taken under their old names:
rename_deviceold/new(nowtag/new_tag),renameofset_potential,set_fluid_groupandset_pct_loop(nownew_name),replace_texttext/with(nowfind/replace). -
Parts server:
--server/--token, theOPENECRAFT_SERVER/OPENECRAFT_TOKENenvironment variables or theparts_connecttool (also withuser/password); default the public parts serverhttps://parts-server.openecraft.org(public parts server).parts_connectwithkind: Eplanreads the EPLAN Data Portal instead (the token is the personal access token; searching,parts_get,parts_fileandparts_check_updatesonly). The data portal tools search with facets (parts_search), manage catalogs, files, favorites and users (parts_catalog_save,parts_attach,parts_favorites,parts_user_save, …), compare the project parts with the server (parts_check_updates) and share the company's forms (parts_company_forms(publish)). -
Help and messages follow
--langor the system language; the MCP server answers in English unless--langis given. -
OPENECRAFT_MCP_ROOTis the folder the files of the MCP tools must be in (path,output,folder,database,targetand template files); default the working folder of the server,*allows every folder. An agent misled by text it reads (a project, a part, a web page) cannot read or overwrite files elsewhere, such as other projects or plugin folders. Relative paths are inOPENECRAFT_MCP_ROOT, also when the client starts the server in a folder of its own (Claude Desktop); the instructions of the server name the folder to the agent. -
OPENECRAFT_MCP_TOOLSchooses the tools the MCP server offers. By default it offers the core tools for schematics (core, about 50: projects, pages, symbols, wires, cables, parts, check, reports, exports; about 30 kB) and reaches the others (all of them together describe themselves in about 260 kB) through three tools of its own:find_tools(names, or the tools whose name or description has the words of a query),describe_tool(description and parameters) andcall_tool(calls any tool by its name). Names separated by commas choose other tools,parts_*all tools starting withparts_,*all of them (e.g.core,panel*,parts_*). -
Without a parts server
parts_searchandparts_getuse the parts of the project and the built-in catalog (parts_search --localalways), andassign_partnames similar parts for a number it does not know. -
new_project --pathdoes not replace an existing file unlessoverwriteis given.search_projectssearches the current folder unless a database or folder is given.
The MCP server is openecraft-cli of the packages: on Windows the setup component
Command line and MCP server (installation type Full, not part of Editor), in
%LOCALAPPDATA%\Programs\OpenECraft\ (or C:\Program Files\OpenECraft\ for all
users); on macOS /Applications/OpenECraft.app/Contents/MacOS/openecraft-cli; on Linux
/usr/bin/openecraft-cli (deb, rpm), ~/.local/bin (tar.gz), <AppImage> cli,
flatpak run --command=openecraft-cli io.github.nilres.OpenECraft or openecraft.cli
(snap). Register it with an agent, e.g. Claude Code (started in the folder of the
projects):
claude mcp add openecraft -- /path/to/openecraft-cli mcp
claude mcp add --scope user -e OPENECRAFT_MCP_ROOT=/home/me/projects openecraft -- openecraft-cli mcp
or in the mcpServers configuration of other clients (Claude Desktop:
claude_desktop_config.json in %APPDATA%\Claude\, ~/Library/Application Support/Claude/
or ~/.config/Claude/; Cursor: ~/.cursor/mcp.json; VS Code: .vscode/mcp.json with
servers instead of mcpServers):
{ "mcpServers": { "openecraft": { "command": "openecraft-cli", "args": ["mcp"],
"env": { "OPENECRAFT_MCP_ROOT": "/home/me/projects" } } } }
The agent can read and write any file the server process can access; start it in a working directory (and with a parts server token) you are fine with the agent using. Let an AI agent draw your schematic has a worked example with its transcript, example prompts and the setup of more clients.
Plugins
Plugins add commands, checks, reports and exports to the editor (Plugins tab: Plugin
commands lists every command by plugin with a search, the star pins one to the tab; Check
tab), the command line and the MCP server at the same time. Built-in plugins are Rust
code in crates/openecraft-api; external plugins are programs in any language that
answer JSON requests on stdin / stdout:
OPENECRAFT_PLUGINS=examples/plugins openecraft-cli -p pump.oec plugins
openecraft-cli --plugins examples/plugins -p pump.oec report --kind page_notes
See docs/plugins.md for the API and the protocol.