Skip to content
Back to search

NX_MCP

MCP server for Siemens NX (UG) — AI agents control NX GUI via 47+ tools

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dreamending--nx-mcp/badge.svg)](/listings/dreamending--nx-mcp)

HTML

<a href="/listings/dreamending--nx-mcp"><img src="/api/listings/dreamending--nx-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 288 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="docs/assets/readme-hero.svg" width="1200" alt="NX MCP — Local CAD automation for Siemens NX" />
  3. </p>
  4. <h1 align="center">NX MCP</h1>
  5. <p align="center"><strong>Connect MCP clients to Siemens NX for local CAD automation.</strong></p>
  6. <p align="center">
  7. <a href="https://github.com/DreamEnding/NX_MCP/actions/workflows/ci.yml"><img src="https://github.com/DreamEnding/NX_MCP/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  8. <a href="pyproject.toml"><img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&amp;logoColor=white" alt="Python 3.10+" /></a>
  9. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-14B8A6" alt="MIT license" /></a>
  10. <a href="https://github.com/DreamEnding/NX_MCP/stargazers"><img src="https://img.shields.io/github/stars/DreamEnding/NX_MCP?style=flat&amp;color=38BDF8" alt="GitHub stars" /></a>
  11. </p>
  12. <p align="center"><strong>English</strong> · <a href="README.zh-CN.md">简体中文</a></p>
  13. <p align="center"><a href="#quick-start">Quick start</a> · <a href="#tools">Tools</a> · <a href="#example-workflow">Example workflow</a> · <a href="#documentation">Documentation</a></p>
  14. ---
  15. NX MCP exposes 16 typed tools for creating parts, drawing sketches, extruding
  16. solids, inspecting model objects and exporting STEP. A Python MCP server runs
  17. outside NX; a local bridge executes NXOpen calls inside the NX process.
  18. > [!IMPORTANT]
  19. >
  20. > **Development preview — `0.2.0.dev0`.** Historical validation covers Python
  21. > batch mode on NX2506 and the C# GUI bridge on NX2206. Release acceptance for
  22. > the same clean candidate on both environments is still pending.
  23. > See [capabilities and validation](#capabilities-and-validation).
  24. | Sketch & model | Inspect & recover | Save & exchange |
  25. | :--- | :--- | :--- |
  26. | Create sketches, draw lines and rectangles, extrude solids. | Query bodies and features, undo operations and fit the view. | Open and save NX parts, export STEP files. |
  27. ## How it works
  28. ```mermaid
  29. flowchart LR
  30. Client["MCP client"] -->|stdio| Sidecar["Python sidecar"]
  31. Sidecar -->|"Authenticated loopback JSON-RPC"| Bridge["NX bridge: Python or C#"]
  32. Bridge -->|"NXOpen on the main thread"| NX["Siemens NX"]
  33. ```
  34. The sidecar handles tool schemas, input validation and MCP responses. The bridge
  35. owns the NX session, object references, undo marks and model operations. The
  36. sidecar can start without NX; CAD calls require a running bridge.
  37. | Bridge | Use case | Documented runtime |
  38. | --- | --- | --- |
  39. | **C# GUI** | Model in an open NX window; the UI remains available between calls | NX2206 |
  40. | **Python batch** | Run an explicitly enabled, blocking journal loop | NX2506 |
  41. Both bridges expose the same default tool contract. Use **one bridge per state
  42. directory**. See [architecture](docs/architecture.md) for the protocol and
  43. [GUI bridge setup](docs/gui-bridge.md) for scheduling and deployment details.
  44. ## Quick start
  45. ### 1. Install the sidecar
  46. You need **Windows**, a local native **Siemens NX** installation, **Python 3.10+**,
  47. **PowerShell 7**, Git and an MCP client that supports stdio servers. Use a
  48. disposable workspace for your first run.
  49. ```powershell
  50. git clone https://github.com/DreamEnding/NX_MCP.git
  51. Set-Location NX_MCP
  52. python -m venv .venv
  53. .\.venv\Scripts\python.exe -m pip install -e .
  54. New-Item -ItemType Directory -Force 'C:\NX_MCP_WORKSPACE' | Out-Null
  55. ```
  56. Run the following commands from the repository root. Replace the sample NX,
  57. checkout and user paths with your own. If your network requires a proxy,
  58. configure it before cloning or installing packages.
  59. ### 2. Start one NX bridge
  60. <details>
  61. <summary><strong>Option A — Interactive C# bridge</strong></summary>
  62. Build against your installed NX assemblies:
  63. ```powershell
  64. .\nx_gui_bridge\build.ps1 -NxRoot 'C:\Program Files\Siemens\NX2206'
  65. ```
  66. Create `nx_gui_bridge/build/gui-bridge.json` next to the generated DLL:
  67. ```json
  68. {
  69. "workspace": "C:\\NX_MCP_WORKSPACE",
  70. "state_dir": "C:\\Users\\<you>\\.nx-mcp"
  71. }
  72. ```
  73. In NX, choose **File → Execute → NX Open** (`Ctrl+U`) and load
  74. `nx_gui_bridge/build/NxMcpGuiBridge.dll`. Running it again stops the bridge.
  75. Environment variables override the JSON configuration.
  76. Loading an unsigned DLL requires an NX Open .NET author license
  77. (`dotnet_author`); otherwise sign it with NX's `SignDotNet.exe`.
  78. See the [GUI bridge guide](docs/gui-bridge.md) for signing, startup loading and
  79. client AppData isolation.
  80. </details>
  81. <details>
  82. <summary><strong>Option B — Python batch bridge</strong></summary>
  83. In a dedicated PowerShell terminal, set the bridge environment and run the
  84. bundled journal through NX's journal runner:
  85. ```powershell
  86. $env:NX_MCP_WORKSPACE = 'C:\NX_MCP_WORKSPACE'
  87. $env:NX_MCP_STATE_DIR = Join-Path $env:USERPROFILE '.nx-mcp'
  88. $env:NX_MCP_ALLOW_UNVERIFIED_PYTHON_BRIDGE = '1'
  89. $env:NX_MCP_BRIDGE_STOP_FILE = Join-Path $env:NX_MCP_WORKSPACE "bridge-$([guid]::NewGuid()).stop"
  90. Write-Output "Stop the bridge by creating: $env:NX_MCP_BRIDGE_STOP_FILE"
  91. & 'C:\Program Files\Siemens\NX2506\NXBIN\run_journal.exe' (Join-Path (Get-Location) 'examples/start_nx_bridge.py')
  92. ```
  93. This command keeps running while the bridge pumps requests. To stop it, create
  94. the printed stop-file path from another terminal using `New-Item -ItemType File`.
  95. The journal loads this checkout's `src/` automatically; the default Python bridge
  96. needs no MCP or Pydantic installation inside NX. This runner is batch-only.
  97. </details>
  98. ### 3. Configure your MCP client
  99. Use the virtual environment's **absolute Python path**. The workspace and state
  100. directory must match the bridge configuration, including the real username in
  101. place of `<you>`.
  102. ```json
  103. {
  104. "mcpServers": {
  105. "nx-mcp": {
  106. "command": "C:\\src\\NX_MCP\\.venv\\Scripts\\python.exe",
  107. "args": ["-m", "nx_mcp.server"],
  108. "env": {
  109. "NX_MCP_WORKSPACE": "C:\\NX_MCP_WORKSPACE",
  110. "NX_MCP_STATE_DIR": "C:\\Users\\<you>\\.nx-mcp"
  111. }
  112. }
  113. }
  114. }
  115. ```
  116. Reload the client and call `nx_status`. A connected bridge returns
  117. `connected: true`, its NX version and `bridge_implementation` (`python_batch`
  118. or `csharp_gui`). With no work part, `active_part` and `units` are `null`.
  119. If you receive `NX_BRIDGE_UNAVAILABLE`, check that the bridge is running and
  120. that both processes use the same absolute `NX_MCP_STATE_DIR`.
  121. ## Tools
  122. The default `tools/list` contains exactly **16 tools**:
  123. | Area | Tools |
  124. | --- | --- |
  125. | Session | `nx_status` |
  126. | Part files | `nx_create_part`, `nx_open_part`, `nx_save_part`, `nx_close_part` |
  127. | Export | `nx_export_step` |
  128. | Inspection | `nx_list_sketches`, `nx_list_bodies`, `nx_list_features` |
  129. | Sketches | `nx_create_sketch`, `nx_sketch_line`, `nx_sketch_rectangle`, `nx_finish_sketch` |
  130. | Modeling | `nx_extrude` |
  131. | Recovery and view | `nx_undo`, `nx_fit_view` |
  132. Tools publish typed inputs, structured results and MCP operation hints. Geometry
  133. inputs use the work part's **native units**, reported by `nx_status.units` as
  134. `mm` or `inch`. If units are missing or `null`, confirm them before modeling.
  135. The 34 legacy tools are hidden and unverified. Their opt-in settings are
  136. explained in the [0.1 migration guide](docs/migration-0.2.md); the C# bridge does
  137. not support them. STEP-to-USD conversion is a [separate validation example](docs/usd-validation.md),
  138. not an MCP tool. Measurement APIs remain [proposals](docs/inspection-contract.md).
  139. ## Example workflow
  140. Create a **20 × 10 × 12.5 mm** block in a new part. These are MCP tool calls,
  141. not a Python script; pass each row's arguments through your client.
  142. Use fresh output paths and confirm the intended work part before making changes.
  143. | Step | Tool | Arguments or result to retain |
  144. | --- | --- | --- |
  145. | 1 | `nx_status` | Check the active part and connection |
  146. | 2 | `nx_create_part` | `{"path":"demo/block.prt","units":"mm"}` |
  147. | 3 | `nx_create_sketch` | `{"plane":"XY"}`; retain `object.id` as `sketch_id` |
  148. | 4 | `nx_sketch_rectangle` | `{"sketch_id":"<id>","corner1":{"x":0,"y":0},"corner2":{"x":20,"y":10}}` |
  149. | 5 | `nx_finish_sketch` | `{"sketch_id":"<id>"}` |
  150. | 6 | `nx_extrude` | `{"sketch_id":"<id>","distance":12.5}` |
  151. | 7 | `nx_list_bodies`, `nx_list_features` | Check the returned body and feature |
  152. | 8 | `nx_save_part` | `{}` |
  153. | 9 | `nx_export_step` | `{"path":"demo/block.stp"}` |
  154. Replace `<id>` with the actual sketch ID from step 3. The example uses XY;
  155. XZ/YZ line and rectangle coordinate handling currently needs correction.
  156. Object lists verify model structure, not exact dimensional measurements.
  157. The [NX modeling skill](skills/nx-modeling/SKILL.md) describes unit handling,
  158. part ownership, verification and recovery for agents.
  159. ## Operational boundaries
  160. - **Files:** pass paths relative to `NX_MCP_WORKSPACE`. Both processes validate
  161. file boundaries. Geometry commands operate on the current work part, so
  162. establish the target part before editing.
  163. - **Save and close:** operate on the work part, not its whole assembly tree.
  164. An incomplete save returns an error, preserves undo history and prevents
  165. save-before-close from discarding the part.
  166. - **Object IDs:** are session references, not permanent asset IDs. Query fresh
  167. IDs after undo, failed-mutation rollback or closing/reopening a part.
  168. - **Recovery:** never automatically replay a mutation whose
  169. `details.execution_state` is `unknown`. Inspect the model first. A rollback
  170. failure blocks writes until explicit recovery; see the [recovery contract](docs/architecture.md#object-and-operation-lifecycle).
  171. - **Local access:** the bridge binds to `127.0.0.1` and authenticates requests.
  172. Keep the state directory private: `bridge.json` contains the session token.
  173. Remote exposure and Teamcenter-managed sessions are outside the current scope.
  174. ## Capabilities and validation
  175. Default availability, automated tests and real-NX acceptance are separate claims.
  176. | Area | Evidence and remaining boundary |
  177. | --- | --- |
  178. | Default modeling workflow | Development-tree NX2506 batch acceptance; clean release-candidate matrix pending |
  179. | Interactive GUI bridge | Historical NX2206 acceptance; matching current-candidate acceptance pending |
  180. | Native units | Metric/inch save/reopen verified on development-tree Python/NX2506; GUI runtime validation pending |
  181. | Failure and recovery paths | Local fault-injection tests; no blanket real-NX acceptance of every error branch |
  182. | Legacy tools and USD conversion | Outside the default tool surface; separate validation requirements |
  183. See [real-NX validation](docs/real-nx-validation.md), [M1 status](docs/m1-status.md),
  184. [M2 status](docs/m2-status.md) and the [release checklist](RELEASE.md) for exact
  185. builds, dates and acceptance criteria. A fake-NX test or successful C# build does
  186. not certify native CAD behavior.
  187. ## Development
  188. Use the repository virtual environment from PowerShell 7:
  189. ```powershell
  190. .\.venv\Scripts\Activate.ps1
  191. python -m pip install -e ".[dev]"
  192. python -m pre_commit install --install-hooks
  193. python -m pre_commit run --all-files
  194. python -m mypy src/nx_mcp
  195. python -m pytest -q -p no:cacheprovider -m "not real_nx" --cov=nx_mcp --cov-branch --cov-fail-under=78
  196. ```
  197. Ordinary tests do not require NX. CI runs Python tests, coverage, packaging,
  198. contract parity and isolated Windows C# harnesses. Real-NX acceptance runs
  199. separately on a dedicated runner. See [contributing](CONTRIBUTING.md) before
  200. adding tools or collecting release evidence.
  201. ## Documentation
  202. | Guide | What it covers |
  203. | --- | --- |
  204. | [Architecture](docs/architecture.md) | Process boundaries, protocol, object lifecycle and recovery |
  205. | [GUI bridge](docs/gui-bridge.md) | C# build, configuration, loading and NX2206 evidence |
  206. | [Real-NX validation](docs/real-nx-validation.md) | Batch setup, acceptance commands and runtime evidence |
  207. | [NX modeling skill](skills/nx-modeling/SKILL.md) | Agent workflow using the existing tools |
  208. | [0.1 → 0.2 migration](docs/migration-0.2.md) | Tool and parameter changes |
  209. | [MCP SDK v2 migration](docs/migration-mcp-sdk-2.md) | Official Python SDK dependencies and client compatibility |
  210. | [STEP → USD validation](docs/usd-validation.md) | Independent conversion and geometry checks |
  211. | [Inspection contract](docs/inspection-contract.md) | Implemented units and proposed measurement APIs |
  212. [Changelog](CHANGELOG.md) · [Release checklist](RELEASE.md) · [Security policy](SECURITY.md) · [MIT license](LICENSE)
  213. ## Star History
  214. If NX MCP helps your workflow, give it a star or share your feedback in an issue.
  215. <p align="center">
  216. <a href="https://star-history.com/#DreamEnding/NX_MCP&amp;Date">
  217. <picture>
  218. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=DreamEnding/NX_MCP&amp;type=Date&amp;theme=dark" />
  219. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=DreamEnding/NX_MCP&amp;type=Date" />
  220. <img width="800" alt="NX MCP GitHub star history" src="https://api.star-history.com/svg?repos=DreamEnding/NX_MCP&amp;type=Date" />
  221. </picture>
  222. </a>
  223. </p>
  224. [Explore the chart](https://star-history.com/#DreamEnding/NX_MCP&Date)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.