fusion-spatial-mcp

An MCP server that gives AI agents genuine 3D spatial understanding of Autodesk Fusion 360 — exact measurements, collision/clearance/containment, volumetric occupancy, section cuts, engineering multiviews, and free-space placement search — plus Fusion-native parametric authoring: constrained sketches, timeline features, and named user parameters, aimed at producing clean, human-editable parametric models.

The design is Fusion-first: tools are built around Fusion's own concepts (feature timeline, sketch constraints, user parameters, components), not adapted from any other CAD paradigm. Under the hood, the geometry-reading layer reuses the platform-neutral spatial-core engine: a CAD platform only has to provide two adapter functions (bodies() + tessellate()), validated by that repo's JSON Schema conformance suite — spatial understanding of B-Rep solids is the same no matter how the geometry was authored.

Claude ──stdio── Node MCP server ──TCP 127.0.0.1:8767── Fusion add-in (Python)
                     └── spatial-core                        └── CustomEvent → main thread

Status: working end to end. Adapter conformance (F2) passed; six-question spatial benchmark 6/6 (F3); parametric-bracket authoring acceptance passed (F4): constrained sketch → extrude → hole → 2×2 pattern → fillet, six named user parameters, resized purely via parameter driving, dimensions verified numerically by the spatial tools.

Setup

1. Build the server (Node 22+; the sibling spatial-core repo must be cloned next to this one for the file: dependency):

   npm install
   npm run build
   

2. Install the add-in — link (or copy) addin/FusionSpatialMCP into Fusion's dev add-ins folder:

   New-Item -ItemType Junction `
     -Path "$env:APPDATA\Autodesk\Autodesk Fusion 360\API\AddIns\FusionSpatialMCP" `
     -Target "<repo>\addin\FusionSpatialMCP"
   

3. Run the add-in: in Fusion press Shift+S → Add-Ins tab → FusionSpatialMCP → Run. The Text Commands palette logs listener running on 127.0.0.1:8767. Re-run after editing the add-in file. (Check Run on Startup to make it permanent.)

4. Register the MCP server with your client, e.g. for Claude Code:

   claude mcp add fusion -- node <repo>/dist/index.js
   

Using it (agent workflow)

• Orient first: fusion_document — document, units, up-axis, and the feature timeline (in Fusion, the timeline IS the scene graph).
• Any metric question (size, position, distance, clearance, hollowness, wall thickness): use the space_* tools, never screenshots — they return exact numbers. space_digest inventories every body with kernel-exact volume/area/centroid; bodies get short handles (b1, b2, …).
• Sub-body granularity: fusion_find_geometry scans faces/edges analytically (find the ⌀3 holes: kind='cylinder_face', radius=1.5) and returns self-healing handles (f1, e2) that feed fillet/chamfer/sketch- plane/shell inputs and fusion_measure_relation — exact design-intent verdicts like "is this hole coaxial with that boss?" (Patterns adapted from Fusion-Essentials, MIT/Apache-2.0.)
• Authoring is parametric by default. Every dimension input accepts a number (doc units), an expression ("40 mm", "width/2"), or {param: "wall_height", value: "40 mm"} which creates a named user parameter on the fly. fusion_create_sketch takes entities + dimensions + constraints in one call and reports fullyConstrained; fusion_add_feature appends ONE timeline feature per call and returns a health report. Editing = driving parameters: fusion_set_parameters (batch, one recompute) or fusion_edit_feature (a feature's dimensions by role). fusion_timeline / fusion_rollback for history introspection and mid-history edits. fusion_execute_api_script is the escape hatch (adsk/app/ui preloaded, assign to result).
• Quality bar: would a mechanical designer be happy to inherit this timeline? Named features, named parameters, fully-constrained sketches.

Tool surface

Development

• node tools/call.mjs <method> [json | @file.py] — raw wire calls (ping, fusion.document, fusion.execute @script.py, …)
• npm run conformance — adapter conformance suite (canonical contracts + suite live in the spatial-core package); must print CONFORMANT
• node tools/f2-checks.mjs — volumes vs. Fusion physical properties + world-space proxy tessellation (needs the tools/f2-scene.py scene)
• node tools/f3-benchmark.mjs — six-question spatial benchmark (≥5/6)
• node tools/f4-bracket.mjs — parametric bracket authoring acceptance
• docs/BUILD_PLAN.md — the phased build plan with the Fusion API traps (internal units are ALWAYS cm; face sketches flip normals; API rectangles have no constraints; …)

MIT licensed.