MCP Directory

How to add build123d-mcp to Windsurf

Exposes build123d CAD operations as MCP tools so AI assistants can build, inspect, and iterate on 3D geometry interactively. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 25★ · stdio · no auth

Windsurf config for build123d-mcp

pip install build123d-mcp
{
  "mcpServers": {
    "build123d-mcp": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--python",
        "3.12",
        "build123d-mcp@latest"
      ]
    }
  }
}

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the build123d-mcp config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5build123d-mcp's tools become available to Cascade.

Before you start

  • uv (astral-sh/uv) — used to fetch and launch the server
  • An MCP-compatible client (Claude Code, Claude Desktop, Cursor, VS Code/Continue/Copilot, etc.)
  • Python 3.11, 3.12, 3.13, or 3.14 (uv can auto-download a managed interpreter)
  • All Python deps (build123d, vtk, etc.) are installed automatically by uv

What build123d-mcp can do in Windsurf

execute

Run build123d Python code in a persistent session; use show(shape, name) to register named parts.

reset

Clear the session back to empty state (namespace, shapes, snapshots).

measure

Full geometric summary: volume, area, topology, bounding box, centre of mass, inertia tensor, face-type inventory.

clearance

Minimum distance (mm) between two named shapes.

cross_sections

Cross-sectional areas at evenly spaced planes along X/Y/Z; useful for detecting voids and wall-thickness variation.

resolve

Evaluate a selector expression (e.g. .faces().filter_by(Axis.Z).last()) against a named object and return a geometry descriptor.

find_holes

Feature recognition: coaxial drill + counterbore + spotface stacks reported as one hole record (axis, location, diameter, depth, bottom type).

find_bosses

Feature recognition: external bosses with height.

Security

Ships with defence-in-depth sandboxing applied before any user code runs: (1) AST inspection that rejects non-allowlisted imports and blocks eval/exec/compile/open and dunder attribute access; (2) restricted builtins with __import__ rewrapped to enforce the allowlist at runtime; (3) a wall-clock exec timeout (default 120s, --exec-timeout N) enforced via SIGALRM with worker restart on breach. Filesystem, networking, and shell modules are blocked, and path traversal is rejected for export()/render_view(save_to=). Not a perfect sandbox (memory is unbounded; introspection chains could in principle escape) — for untrusted input wrap the whole server in an OS-level sandbox (e.g. @anthropic-ai/sandbox-runtime or a container). --allow-imports / --allow-all-imports / --no-sandbox relax the policy and should be used only in trusted/isolated environments. The --library directory is treated as trusted input — point it only at directories you control. HTTP mode shares a single CAD session across all requests unless per-request session middleware is installed; do not expose it to multiple users without that.

build123d-mcp + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the build123d-mcp config there under the "mcpServers" key and restart the client.

Is build123d-mcp safe to use with Windsurf?

Ships with defence-in-depth sandboxing applied before any user code runs: (1) AST inspection that rejects non-allowlisted imports and blocks eval/exec/compile/open and dunder attribute access; (2) restricted builtins with __import__ rewrapped to enforce the allowlist at runtime; (3) a wall-clock exec timeout (default 120s, --exec-timeout N) enforced via SIGALRM with worker restart on breach. Filesystem, networking, and shell modules are blocked, and path traversal is rejected for export()/render_view(save_to=). Not a perfect sandbox (memory is unbounded; introspection chains could in principle escape) — for untrusted input wrap the whole server in an OS-level sandbox (e.g. @anthropic-ai/sandbox-runtime or a container). --allow-imports / --allow-all-imports / --no-sandbox relax the policy and should be used only in trusted/isolated environments. The --library directory is treated as trusted input — point it only at directories you control. HTTP mode shares a single CAD session across all requests unless per-request session middleware is installed; do not expose it to multiple users without that.

How do I add it to Claude Desktop or Cursor?

Add an mcpServers entry with command "uv" and args ["tool", "run", "--python", "3.12", "build123d-mcp@latest"] to the client's config (claude_desktop_config.json, ~/.cursor/mcp.json, or .mcp.json for Claude Code), then restart the client. The server runs over stdio and uv fetches the package on launch; no clone or prior install is required.

Which Python versions are supported?

Python 3.11, 3.12, 3.13, and 3.14 are all supported and CI-tested. The example config passes --python 3.12 as a widely-available default, but you can swap in any supported interpreter; uv will auto-download a managed Python if you don't have one.

Is it safe to run LLM-generated CAD code?

It ships with defence-in-depth sandboxing (AST import allowlist, restricted builtins with eval/exec/open/__import__ guarded, and a SIGALRM exec timeout); filesystem, network, and shell modules are blocked. It is not a perfect sandbox, so for truly untrusted input the README recommends wrapping the whole server in an OS-level sandbox such as @anthropic-ai/sandbox-runtime or a container.

View repo Full build123d-mcp page