NX MCP Server

NX MCP is a local Model Context Protocol server for Siemens NX automation. The 0.2.0.dev0 line replaces the unverified direct-attach design with two explicit processes:

MCP client <--stdio--> Python sidecar <--authenticated loopback JSON-RPC--> NX bridge <--NXOpen--> NX

The sidecar can start without NX. Tool calls fail with NX_BRIDGE_UNAVAILABLE until an NX journal starts the bridge.

Current status

The sidecar, bridge protocol, input/output schemas, workspace confinement, and core workflow have automated coverage. The Python bridge passed the documented 20-run batch workflow on Siemens NX 2506 (ugraf 2506.4021) on 2026-08-21. It remains opt-in while a non-blocking NX GUI event pump is validated; the bundled Python Journal runner is intentionally batch-only. The safety-hardening changes have local regression coverage. A development-tree M1 run on 2026-09-30 passed a fresh 20-iteration NX2506 batch loop, all 16 tools, negative cases and process restart. Release still requires the same clean candidate on both Python batch/NX2506 and C# GUI/NX2206; see M1 status.

The default tools/list exposes only these 16 tools:

• Status: nx_status
• Files: nx_create_part, nx_open_part, nx_save_part, nx_close_part, nx_export_step
• Queries: nx_list_sketches, nx_list_bodies, nx_list_features
• Sketch: nx_create_sketch, nx_sketch_line, nx_sketch_rectangle, nx_finish_sketch
• Modeling: nx_extrude
• Recovery/view: nx_undo, nx_fit_view

The 34 old tools outside the certified surface remain unverified and hidden by default. NX_MCP_ENABLE_EXPERIMENTAL=1 registers them through the bridge; Journal tools additionally require NX_MCP_ENABLE_JOURNAL=1.

Agent modeling workflow

The canonical NX modeling skill explains discovery, part ownership, units, sketch/extrude sequencing, result checks, and recovery. It composes existing tools; it does not add permissions or replace code-enforced safety checks. Read it from this checkout; no global skill installation or agent-directory copies are created automatically.

Capabilities and validation

"Implemented", "default", "locally tested", and "real-NX accepted" are separate claims. The historical target is native NX 2506 (ugraf 2506.4021), batch mode; there is no blanket certification of every tool or failure branch.

Capability	Availability	Local evidence	Current real-runtime boundary
Rectangle/sketch/extrude, queries, STEP, undo, save/reopen	Default tools	Automated core workflow tests	Development-tree NX2506 batch loop passed 2026-09-30; clean release-candidate matrix pending
Other default-tool branches, including sketch lines	Default tools	Automated tests	Only scenarios explicitly recorded in the acceptance guide are accepted
Authentication, workspace boundaries, stale/wrong-kind IDs	Enforced by default	Boundary and fake-NX tests	Development-tree NX2506 negative cases passed 2026-09-30; clean release-candidate matrix pending
Uncertain execution and forced rollback failure	Enforced recovery rules	Local fault injection	No real-NX fault-injection acceptance claimed
Bridge/process restart	Existing lifecycle	Automated bridge tests	Development-tree Python/NX2506 process restart passed 2026-09-30; GUI and clean release-candidate matrix pending
Interactive GUI scheduling	C# add-in in nx_gui_bridge/, loaded on demand	Protocol checks against the live add-in	NX2206 acceptance only (2026-09-18, re-validated 2026-09-20); see GUI bridge
Legacy tools / arbitrary Journals	Disabled by default	Mock-NX coverage only	Unverified; explicit opt-in is not certification
STEP-to-USD sample validation	Separate example, not MCP	Unit tests and opt-in OpenUSD checker fixtures	Fresh NX STEP-to-USD chain remains pending

See real NX evidence for dates and exact coverage. nx_status.bridge_implementation identifies python_batch or csharp_gui. The sidecar reports unknown for an older protocol-v1 bridge that omits this field; update that bridge before collecting release evidence. Session object IDs are not permanent asset IDs. Saving/closing the work part must not be described as saving/closing all assembly components.

Independent STEP-to-USD validation

The USD validation guide runs a small acceptance script in a separate Python 3.12 converter environment. It verifies the STEP block from this run, its converted mesh, units, world-space dimensions, and dependencies. Neither the NX interpreter nor the sidecar needs usd-convert-cad or pxr. No nx_export_usd tool, SDK/schema change, or default CI dependency is introduced.

MCP SDK v2 support

The sidecar now uses the official Python SDK mcp>=2.2,<3 and pydantic>=2.12,<3, with Python 3.10+ retained. MCPServer replaces the SDK's old FastMCP class; this is not a migration to the separate FastMCP package. Modern clients use MCP 2026-07-28 discovery over stdio, while initialize-based clients remain supported. The smoke client negotiates automatically.

Default tools, JSON field names on the wire, existing NX error codes, and the internal NX bridge protocol v1 remain unchanged. The SDK major version is independent of this project's 0.2.0.dev0 release gate. See MCP SDK v2 migration for setup and compatibility.

Requirements

See CONTRIBUTING.md for development and evidence requirements, SECURITY.md for private vulnerability reporting, and RELEASE.md for the 0.2.0 gate. Changes are recorded in CHANGELOG.md.

• Windows with a local native Siemens NX installation (validated on NX 2506)
• Python 3.10+
• The package installed in the sidecar interpreter
• An NX journal that can import nx_mcp (the bundled Journal examples load the checkout's src directory automatically; the NX side has no mcp or pydantic dependency)
• A dedicated test/project directory configured as NX_MCP_WORKSPACE

Install the sidecar and development dependencies in a dedicated environment from PowerShell 7 (do not reuse an interpreter still running SDK v1):

$env:NO_PROXY = "localhost,127.0.0.1"
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

Use the absolute path to .venv/Scripts/python.exe as the MCP client's command below, or activate this environment before using python commands.

Internal feasibility run

1. Set NX_MCP_WORKSPACE to a disposable directory.
2. For the target-build feasibility test only, set NX_MCP_ALLOW_UNVERIFIED_PYTHON_BRIDGE=1 in the NX environment.
3. Set NX_MCP_BRIDGE_STOP_FILE to a new path inside the workspace, then run examples/start_nx_bridge.py as an NX journal. The canonical invocation is run_journal.exe <journal-file>, with no extra switches. The journal pumps requests on NX's main thread and writes an authenticated session descriptor to %LOCALAPPDATA%\nx-mcp\bridge.json.
4. Configure the MCP client to launch the sidecar:

{
  "mcpServers": {
    "nx-mcp": {
      "command": "python",
      "args": ["-m", "nx_mcp.server"],
      "env": {
        "NX_MCP_WORKSPACE": "D:\\NX_MCP_WORKSPACE"
      }
    }
  }
}

5. Run the real-NX acceptance loop from an external PowerShell 7 terminal:

python -m nx_mcp.real_smoke --workspace D:\NX_MCP_WORKSPACE --iterations 20 --run-prefix acceptance

6. Create the configured stop file when finished; the journal stops the bridge cleanly.

Do not use production parts for this test. The batch bridge is not evidence of interactive GUI responsiveness; use a non-blocking NX UI scheduler or the agreed minimal C# NX-side bridge before enabling an interactive pilot.

Interactive NX GUI bridge

For live modeling in an open NX window, build and load the C# add-in in nx_gui_bridge/ instead of the batch journal. It serves the same bridge protocol, so the sidecar and MCP tools are unchanged. See GUI bridge for the build, configuration, limits and the NX2206 validation record.

NX_MCP_STATE_DIR moves bridge.json out of %LOCALAPPDATA%\nx-mcp. Set it on both sides when an MSIX-packaged MCP client and NX see different AppData folders. It must be an absolute path, so that the NX bridge and the sidecar name the same file. bridge.json carries the session token, so choose a directory only your account can read; the C# add-in additionally writes the descriptor with a rule that allows your account alone. Both bridges also keep a bridge.lock there and take it while they start, so two NX processes sharing a state directory cannot both claim the descriptor: the second one refuses to start while the first still answers on its port.

Security model

• IPC binds only to 127.0.0.1 on a random port and requires a random 256-bit session token.
• Every file argument is relative to NX_MCP_WORKSPACE; traversal, absolute paths, and resolved links outside the workspace are rejected.
• Journal execution and all 34 legacy tools are disabled by default. Both the sidecar and NX bridge must receive the opt-in environment flags.
• Object IDs are opaque and valid only for the current part session. Undo and failed mutation rollback invalidate references; query new IDs before use.
• Save validates the active part's path; save and close affect only the work part, not its assembly tree. A failed rollback blocks writes until recovery.
• Timeout/disconnect errors distinguish not_started from unknown execution. Never automatically replay an uncertain mutation; inspect the model first.

Local quality gates

The ordinary suite does not require NX. Install the Git hooks once, then use the same checks as CI:

python -m pip install -e ".[dev]"
python -m pre_commit install --install-hooks
python -m pre_commit run --all-files
python -m pytest -q -p no:cacheprovider -m "not real_nx" --basetemp .pytest-tmp

The pre-commit hook runs file and style checks. The pre-push hook runs the non-real-NX pytest suite and the sidecar mypy gate. Tests marked legacy cover the opt-in 0.1 surface; tests marked fake_nx do not validate NXOpen itself. Hosted CI runs the core suite across supported Python and OS combinations, runs legacy mock-NX tests separately, and enforces at least 78% branch coverage in its canonical Ubuntu/Python 3.12 coverage job.

Real NX acceptance is intentionally separate. Dispatch .github/workflows/real-nx.yml from a dedicated self-hosted Windows runner labelled self-hosted, windows, and nx, with NX_RUN_JOURNAL set to the absolute path of run_journal.exe.

See architecture, 0.1 migration, MCP SDK v2 migration, and real NX validation for implementation and release gates.

Star History

The chart updates automatically when this repository receives a star and daily at 04:37 UTC (12:37 Asia/Shanghai). Changes to the Star History workflow on master also trigger an update; manual runs remain available in GitHub Actions. Daily refreshes reconcile missed events and removed stars. GitHub may delay scheduled runs, so the chart is not a real-time counter. Charts are published to the dedicated star-history branch without changing master.