NX

NX MCP exposes 16 typed tools for creating parts, drawing sketches, extruding solids, inspecting model objects and exporting STEP. A Python MCP server runs outside NX; a local bridge executes NXOpen calls inside the NX process.

[!IMPORTANT]

Development preview — 0.2.0.dev0. Historical validation covers Python batch mode on NX2506 and the C# GUI bridge on NX2206. Release acceptance for the same clean candidate on both environments is still pending. See capabilities and validation.

How it works

flowchart LR
    Client["MCP client"] -->|stdio| Sidecar["Python sidecar"]
    Sidecar -->|"Authenticated loopback JSON-RPC"| Bridge["NX bridge: Python or C#"]
    Bridge -->|"NXOpen on the main thread"| NX["Siemens NX"]

The sidecar handles tool schemas, input validation and MCP responses. The bridge owns the NX session, object references, undo marks and model operations. The sidecar can start without NX; CAD calls require a running bridge.

Both bridges expose the same default tool contract. Use one bridge per state directory. See architecture for the protocol and GUI bridge setup for scheduling and deployment details.

Quick start

1. Install the sidecar

You need Windows, a local native Siemens NX installation, Python 3.10+, PowerShell 7, Git and an MCP client that supports stdio servers. Use a disposable workspace for your first run.

git clone https://github.com/DreamEnding/NX_MCP.git
Set-Location NX_MCP
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
New-Item -ItemType Directory -Force 'C:\NX_MCP_WORKSPACE' | Out-Null

Run the following commands from the repository root. Replace the sample NX, checkout and user paths with your own. If your network requires a proxy, configure it before cloning or installing packages.

2. Start one NX bridge

Build against your installed NX assemblies:

.\nx_gui_bridge\build.ps1 -NxRoot 'C:\Program Files\Siemens\NX2206'

Create nx_gui_bridge/build/gui-bridge.json next to the generated DLL:

{
  "workspace": "C:\\NX_MCP_WORKSPACE",
  "state_dir": "C:\\Users\\<you>\\.nx-mcp"
}

In NX, choose File → Execute → NX Open (Ctrl+U) and load nx_gui_bridge/build/NxMcpGuiBridge.dll. Running it again stops the bridge. Environment variables override the JSON configuration.

Loading an unsigned DLL requires an NX Open .NET author license (dotnet_author); otherwise sign it with NX's SignDotNet.exe. See the GUI bridge guide for signing, startup loading and client AppData isolation.

In a dedicated PowerShell terminal, set the bridge environment and run the bundled journal through NX's journal runner:

$env:NX_MCP_WORKSPACE = 'C:\NX_MCP_WORKSPACE'
$env:NX_MCP_STATE_DIR = Join-Path $env:USERPROFILE '.nx-mcp'
$env:NX_MCP_ALLOW_UNVERIFIED_PYTHON_BRIDGE = '1'
$env:NX_MCP_BRIDGE_STOP_FILE = Join-Path $env:NX_MCP_WORKSPACE "bridge-$([guid]::NewGuid()).stop"
Write-Output "Stop the bridge by creating: $env:NX_MCP_BRIDGE_STOP_FILE"
& 'C:\Program Files\Siemens\NX2506\NXBIN\run_journal.exe' (Join-Path (Get-Location) 'examples/start_nx_bridge.py')

This command keeps running while the bridge pumps requests. To stop it, create the printed stop-file path from another terminal using New-Item -ItemType File. The journal loads this checkout's src/ automatically; the default Python bridge needs no MCP or Pydantic installation inside NX. This runner is batch-only.

3. Configure your MCP client

Use the virtual environment's absolute Python path. The workspace and state directory must match the bridge configuration, including the real username in place of <you>.

{
  "mcpServers": {
    "nx-mcp": {
      "command": "C:\\src\\NX_MCP\\.venv\\Scripts\\python.exe",
      "args": ["-m", "nx_mcp.server"],
      "env": {
        "NX_MCP_WORKSPACE": "C:\\NX_MCP_WORKSPACE",
        "NX_MCP_STATE_DIR": "C:\\Users\\<you>\\.nx-mcp"
      }
    }
  }
}

Reload the client and call nx_status. A connected bridge returns connected: true, its NX version and bridge_implementation (python_batch or csharp_gui). With no work part, active_part and units are null.

If you receive NX_BRIDGE_UNAVAILABLE, check that the bridge is running and that both processes use the same absolute NX_MCP_STATE_DIR.

Tools

The default tools/list contains exactly 16 tools:

Tools publish typed inputs, structured results and MCP operation hints. Geometry inputs use the work part's native units, reported by nx_status.units as mm or inch. If units are missing or null, confirm them before modeling.

The 34 legacy tools are hidden and unverified. Their opt-in settings are explained in the 0.1 migration guide; the C# bridge does not support them. STEP-to-USD conversion is a separate validation example, not an MCP tool. Measurement APIs remain proposals.

Example workflow

Create a 20 × 10 × 12.5 mm block in a new part. These are MCP tool calls, not a Python script; pass each row's arguments through your client. Use fresh output paths and confirm the intended work part before making changes.

Replace <id> with the actual sketch ID from step 3. The example uses XY; XZ/YZ line and rectangle coordinate handling currently needs correction. Object lists verify model structure, not exact dimensional measurements. The NX modeling skill describes unit handling, part ownership, verification and recovery for agents.

Operational boundaries

• Files: pass paths relative to NX_MCP_WORKSPACE. Both processes validate file boundaries. Geometry commands operate on the current work part, so establish the target part before editing.
• Save and close: operate on the work part, not its whole assembly tree. An incomplete save returns an error, preserves undo history and prevents save-before-close from discarding the part.
• Object IDs: are session references, not permanent asset IDs. Query fresh IDs after undo, failed-mutation rollback or closing/reopening a part.
• Recovery: never automatically replay a mutation whose details.execution_state is unknown. Inspect the model first. A rollback failure blocks writes until explicit recovery; see the recovery contract.
• Local access: the bridge binds to 127.0.0.1 and authenticates requests. Keep the state directory private: bridge.json contains the session token. Remote exposure and Teamcenter-managed sessions are outside the current scope.

Capabilities and validation

Default availability, automated tests and real-NX acceptance are separate claims.

See real-NX validation, M1 status, M2 status and the release checklist for exact builds, dates and acceptance criteria. A fake-NX test or successful C# build does not certify native CAD behavior.

Development

Use the repository virtual environment from PowerShell 7:

.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m pre_commit install --install-hooks
python -m pre_commit run --all-files
python -m mypy src/nx_mcp
python -m pytest -q -p no:cacheprovider -m "not real_nx" --cov=nx_mcp --cov-branch --cov-fail-under=78

Ordinary tests do not require NX. CI runs Python tests, coverage, packaging, contract parity and isolated Windows C# harnesses. Real-NX acceptance runs separately on a dedicated runner. See contributing before adding tools or collecting release evidence.

Documentation

Changelog · Release checklist · Security policy · MIT license

Star History

If NX MCP helps your workflow, give it a star or share your feedback in an issue. Explore the chart