PLAXIS

PLAXIS · MCP

Drive PLAXIS 2D from any MCP client.

Geometry, staged construction, meshing, calculation and results — exposed as tools, over a hardened Windows-local stdio server.

[Quickstart](#quickstart) · [Tools](#tools) · [Clients](#clients) · [Security model](#security-model) · [Architecture](#architecture)

mcp-name: io.github.yixuanzhong/plaxis-mcp

---

▸ v0.3 — set up once, launch from anywhere

Client-neutral by design: Codex, Claude Code, Cursor, VS Code/Copilot and any other conforming local stdio MCP client connect to the same unprefixed server tools.

---

Quickstart

1 — Set up the machine, once.

plaxis-mcp.exe setup

Profiles land in %LOCALAPPDATA%\Caros\PLAXIS-MCP\profiles (override with --profile-dir). Add --skip-credentials to generate profiles now and store passwords later with plaxis-mcp.exe credentials set --profile .

The directory name is historical — it is where the first supported installer wrote —

and is kept because credential_target is derived from it.

2 — Run each role as its own process.

plaxis-mcp.exe serve --role input

plaxis-mcp.exe serve --role output

--config names a profile explicitly and is equivalent. Either way serve takes every endpoint setting from the profile and the password from Windows Credential Manager, and it fails to start if any PLAXIS_* endpoint environment override is present — so a client cannot silently redirect an endpoint or inject a password.

3 — Point a client at it. See Clients; the host never connects at startup, so call the connect tool once PLAXIS is running.

Getting the host

| PyPI | uvx plaxis-mcp serve --role input py -3.13 -m pip install plaxis-mcp | Ordinary Python source distribution. No code signature, no artifact manifest. |

Both expose the same setup, serve, credentials and profiles commands and enforce the same profile binding and environment-override rejection — so PyPI is not a weaker *runtime* posture. It simply carries no supply-chain attestation of its own beyond PyPI's, and it is not what an organization requiring signed binaries should deploy.

Do not install plxscripting into the host environment under either.

Source / developer launch only — not a supported deployment path

A clean CPython 3.13 environment can run the module directly with endpoint environment variables. This path carries the password in the environment and performs no installation binding.

py -3.13 -m pip install .

$env:PLAXIS_ROLE = "input" $env:PLAXIS_INPUT_HOST = "127.0.0.1" $env:PLAXIS_INPUT_PORT = "10000" $env:PLAXIS_BUNDLE_PYTHON = "C:\Path\To\PLAXIS\python.exe" py -3.13 -I -u -m plaxis_mcp.server

For Output, set PLAXIS_ROLE=output and use the PLAXIS_OUTPUT_* variables. Role-specific variables take precedence over the deprecated generic PLAXIS_HOST, PLAXIS_PORT and PLAXIS_PASSWORD fallback. The server accepts stdio only — do not set a non-stdio PLAXIS_MCP_TRANSPORT.

---

Tools

Each process has one immutable role. A client registers Input and Output as separate MCP servers when it needs both.

34 Input tools · 11 Output tools.

• connect() takes no endpoint or credential arguments. It uses only the pinned role configuration, so an agent cannot redirect a stored password to an arbitrary host.
• Role status resources live at plaxis://input/status and plaxis://output/status.
• get_results(phase, result_type_path, fem_type="node", offset=0, limit=200) paginates losslessly. limit is 1–5,000; responses report count, offset, limit, returned_count, has_more, next_offset and results.
• Every object in a result carries path — the exact string to pass back to any reference parameter. list_objects(kind) lists a whole kind that way, with a geometry summary (coordinates, or a parsed bounds for objects that report a bounding box).
• model_state() reports mesh status, the phase table and unassigned materials before a calculate is attempted. It separates blocking (a fault in this model) from unknown (a check that could not run here) and caveats (something PLAXIS does not expose at all — on 2D V22, whether the mesh still matches the geometry), so an empty blocking is never mistaken for a clean bill of health.
• Results live on the Output server, which reads whatever the PLAXIS Output application has open. view_results(phase) on the Input server is what puts a calculated phase there.
• When PLAXIS rejects a call, its own message travels beside ours in plaxis_message (sanitised: no filesystem paths, no frames, capped with the truncation flagged out of band). A failing calculate also carries a per-phase table in details.

---

Clients

All shipped examples are secret-free and use two server entries, one per role. Replace the command with wherever plaxis-mcp.exe lives, or with uvx plaxis-mcp for a PyPI install. Nothing else needs editing — --role finds the shared profiles by itself.

The generic mcp-client-config.json is a minimal mcpServers example for clients using that conventional JSON shape.

Never add a PLAXIS password to version control, command-line arguments, logs, or a

profile file.

---

Security model

• Profiles are bound to one installation. credential_target is derived from installation_root, and worker_python must be an interpreter that discovery links to that same root. Editing any of the three by hand makes the profile fail to load. This is what stops a profile from handing a stored PLAXIS password to an arbitrary executable.
• Environment overrides are rejected, not merged: serve refuses to start when a PLAXIS_* endpoint variable is set.
• Uncertified pairings fail closed. The Python match is exact — a 3.7-series interpreter at any other patch level is a different, uncertified ABI, so it is rejected rather than assumed compatible.
• Ask before mutation. All clients should prompt before call_method and project/file mutators. Do not set an Always Allow-style rule for call_method, open_project or save_project: client approval is generally tool-wide, not argument-scoped.
• Mutation is not undoable. Absolute local and UNC .p2dx paths reachable by PLAXIS are allowed only after user approval. Client approvals and client-side checkpointing cannot restore in-memory PLAXIS state — use disposable projects and backups for all mutation testing.

---

Architecture

PLAXIS-MCP separates the MCP host from PLAXIS's vendor-managed Python runtime:

  MCP client  ──stdio──▶  host (CPython 3.13, mcp 1.26.0)

│ ├─ private local pipe ▼ role-pinned worker (PLAXIS bundled Python) │ ▼ PLAXIS Remote Scripting @ 127.0.0.1

• Client traffic is always MCP over stdio; normal logs and diagnostics go to stderr.
• PLAXIS-MCP never installs packages into, upgrades, or redistributes the PLAXIS Python bundle.

The split is required because the MCP host needs a current Python runtime while PLAXIS ships version-specific scripting environments.

V20 and V21 share the legacy profile: their end-of-life Python is isolated inside the loopback worker and requires organizational security acceptance.

Requirements

• Windows, with a supported local PLAXIS 2D installation and Remote Scripting enabled.
• CPython 3.13 for the MCP host. Supported host range: >=3.13,<3.14.
• One PLAXIS Input and/or Output server listening only on loopback — defaults Input 127.0.0.1:10000, Output 127.0.0.1:10001.
• A selected, certified PLAXIS bundled-Python profile. Do not install plxscripting into t