PLECS-MCP

An MCP server that exposes the complete Plexim PLECS Standalone JSON-RPC interface as MCP tools, built on fastmcp.

Highlights:

• One MCP tool per RPC method (22/22 on PLECS 5.0.6), plus plecs_rpc and plecs_batch escape hatches

• plecs_connect starts PLECS automatically (macOS / Windows / Linux) when the RPC port is closed

• Results are structured JSON; big arrays are auto-written to disk instead of flooding the context

• Read-only RPC calls run concurrently with a simulation; blocking/mutating calls are serialized

• Write guardrails: install dirs are refused, stray paths need PLECS_MCP_ALLOWED_ROOTS, overwrites need overwrite=true

• Irreversible operations (protect, crash) require confirm=true

Requirements

• PLECS Standalone running locally

• RPC enabled in Preferences → RPC (default port 1080)

• Python 3.10+ (tested with 3.13)

Related MCP server: SimuBridge

Install

cd "/Users/guohuawei/Workspace/AI Usecase/PLECS-MCP"
uv venv --python 3.13 .venv
uv pip install -e . --python .venv/bin/python

Run

.venv/bin/python -m plecs_mcp                                   # stdio (local agents)
.venv/bin/python -m plecs_mcp --transport http --port 8765      # remote agents
.venv/bin/plecs-mcp

Codex (~/.codex/config.toml):

[mcp_servers.plecs]
command = "/Users/guohuawei/Workspace/AI Usecase/PLECS-MCP/.venv/bin/python"
args = ["-m", "plecs_mcp"]

Claude Desktop / Cursor (mcpServers JSON):

{
  "mcpServers": {
    "plecs": {
      "command": "/Users/guohuawei/Workspace/AI Usecase/PLECS-MCP/.venv/bin/python",
      "args": ["-m", "plecs_mcp"]
    }
  }
}

Transports: stdio (default), http, sse, streamable-http. Binding a non-loopback host is refused unless PLECS_MCP_ALLOW_REMOTE=1 is set (there is no auth).

Quickstart (3 minutes)

.venv/bin/python examples/quickstart.py --model /path/to/model.plecs
.venv/bin/python examples/quickstart.py --model /path/to/model.plecs \
    --analysis "Loop Gain (AC Sweep)"

Runs connect → load → simulate (summary) → close, prints per-signal min/max/mean/rms and, for AC sweeps, gain crossover + phase margin. Without --model it uses PLECS_EXAMPLE_MODEL or a bundled PLECS demo.

Configuration

Resolution order: environment variables → config.yml → defaults. config.yml is looked up at $PLECS_MCP_CONFIG, then ./config.yml, then the repo root.

plecs:
  host: "127.0.0.1"
  port: 1080
  timeout: 30

Auto-start

plecs_connect(auto_start=True) (default) probes host:port; if the port is closed it locates the newest install for the host OS, launches it, and polls the port for startup_timeout (default 30 s):

Before launching it checks whether a PLECS process already exists (pgrep / tasklist); if so it skips the launch and tells you to enable Preferences → RPC instead of waiting 30 s. Overrides: the app_path argument, PLECS_EXECUTABLE, PLECS_APP_PATH. PLECS RPC is localhost-only, so the MCP server and PLECS must run on the same machine.

Tools

Return shape

Every tool returns a JSON object (structured content):

• dict results as-is; scalars/arrays wrapped as {"result": ...}

• plecs_list_methods → {"methods": [...]}; plecs_compare → {"diff": [...], "entries": [...]}

• plecs_connect → {"ok": true, "capabilities": {...}, ...} or {"ok": false, "hints": [...]}

• plecs_batch → {"count": n, "results": [{"ok": ..., "result"|"error": ...}]}

Data policy (large results)

Writes are refused inside /Applications, /System, /Library, /usr, /bin, /sbin, /etc, and outside PLECS_MCP_ALLOWED_ROOTS. Existing files are never overwritten without overwrite=true.

Concurrency

Measured on PLECS 5.0.6: statistics returns in 0.01 s while a 0.55 s simulation is running, and a second simulate still waits for the first. The client mirrors that:

• read-only calls share a read lock and run concurrently with a simulation

• simulate/analyze/codegen/exportfmu/runScript take a single "blocking" slot (PLECS allows one)

• load/close/save/set/scope/protect take the exclusive write lock, so state never changes mid-run

Verified behaviour (PLECS 5.0.6)

1. simulate returns Values as signals × time over JSON-RPC; summaries normalise both orientations.

2. Models without top-level outports return {"Time": [], "Values": []} and a summary note.

3. Only nested {"SolverOpts": {"TimeSpan": ...}} is honoured; flat {"StopTime": ...} is silently ignored.

4. SolverOpts.Timeout works for both simulate and analyze; AnalysisOpts.Timeout is rejected.

5. analyze needs the analysis Name property; plecs.scope supports no ExportCSV/GetCursorData.

6. plecs.webserver ignores TimeRange/Size; slicing and decimation happen in this server.

7. plecs.save(model, save_as) renames the open model; the session registry follows the rename.

8. plecs.protect(path) takes one subsystem path, returns 0, is idempotent, and only becomes permanent on save.

9. plecs.exportfmu(path) accepts one path and requires an atomic subsystem.

10. plecs.codegen(model) runs and returns Coder diagnostics as an RPC error string.

11. plecs.runScript is listed by system.listMethods but every wire shape tried returns server error: invalid method parameters — kept as experimental with a params override.

12. Business errors still return HTTP 200; the JSON error field becomes a tool error.

13. trust_env=False: macOS system proxies can hijack 127.0.0.1:1080 (HTTP 502), so PLECS is never reached through a proxy.

Known limitations

• The RPC model tree exposes outport names and positions but no port index, so channel i is not auto-labelled; summary.outports is provided instead of guessing.

• .trace files (scope SaveTraces) use a private format and are not parsed.

• Gain crossover/phase margin only make sense for loop-gain AC sweeps; other analysis kinds are labelled.

• Auto-start picks the newest install for the host OS: macOS /Applications/PLECS*.app, Windows %ProgramFiles%\Plexim\*\plecs.exe, Linux plecs on PATH or /opt/plecs*/plecs. Other platforms return unsupported-platform and require a manual start.

• One MCP server instance manages one PLECS instance (localhost).

Example workflows

# parameter sweep (PLECS-native parallel)
plecs_simulate(model, options=[{"ModelVars": {"R": 10}}, {"ModelVars": {"R": 47}}], summary=True)

# Bode / loop gain
plecs_analyze(model, "Loop Gain (AC Sweep)", summary=True)
# → responses[0].gain_crossover_hz / phase_margin_deg / stable

# scope export with client-side slicing
plecs_webserver("getScopeCsv", [f"{model}/Scope"], time_range=[0, 1e-3], decimate=10)

# state space at one switch combination
plecs_state_space(model, {"FET": 1, "D": 0})

# cheap multi-read
plecs_batch([{"method": "plecs.get", "params": [f"{model}/L1", "L"]},
             {"method": "plecs.get", "params": [f"{model}/C1", "C"]}])

Error table

Tests

.venv/bin/python -m pytest -q      # 50 tests

• Unit: base64/model tree, summary maths, config precedence, paths, locks, app discovery/launch

• Surface: all 26 tools registered/documented; destructive tools need confirmation; batch/limits/guards

• Integration: when 127.0.0.1:1080 is reachable, exercises connect/load/tree/get/simulate/summary/CSV on /tmp copies of the bundled demos (user models are never touched)

CI (.github/workflows/ci.yml) runs the unit/surface suite on Python 3.10 and 3.13; integration tests skip automatically when PLECS is not installed.

Layout

src/plecs_mcp/client.py    JSON-RPC client (RW lock, timeouts, logging, no proxy)
src/plecs_mcp/config.py    config.yml + environment resolution
src/plecs_mcp/paths.py     write guardrails and output directories
src/plecs_mcp/session.py   model registry (path, dirty flag, rename tracking)
src/plecs_mcp/codec.py     base64 decoding, tree/compare parsing, CSV slicing
src/plecs_mcp/summary.py   time-series statistics, Bode margins, analysis kinds
src/plecs_mcp/launcher.py  per-OS discovery/launch, port polling, process check
src/plecs_mcp/server.py    26 MCP tools
examples/quickstart.py     end-to-end smoke test
tests/                     unit + surface + integration