Fusion MCP for Codex

This project contains a local plugin for Codex and an add-in for Fusion 360. The idea is that Codex can inspect and automate Autodesk Fusion 360 through MCP.

Architecture

• server/main.py: local MCP server that Codex starts via stdio

• fusion_addin/FusionCodexBridge/: Fusion 360 add-in that exposes a local HTTP bridge at 127.0.0.1:19851

• .mcp.json: tells Codex how to start the local MCP server

The MCP server communicates with the Fusion add-in over authenticated HTTP. The installer generates a private local token and both processes read it from %LOCALAPPDATA%\FusionMCP\credentials.json; the add-in rejects requests that do not present the token. The add-in executes authorized work on Fusion's main thread using a custom event. The manifest installs FusionCodexBridge with runOnStartup=true so the bridge starts automatically when Fusion opens. JSON bodies of POST requests have a default limit of 1 MiB and fusion_run_script remains disabled unless explicitly opted in.

The /health endpoint returns the bridge version and protocolVersion. The MCP client performs a compatibility check before running normal tools and returns a guided error if Fusion is still running an old add-in; fusion_ping and fusion_reload_bridge remain available for diagnostics and reloading.

Related MCP server: fusion360-mcp-server

Tools exposed by the MCP

• fusion_ping

• fusion_status

• fusion_reload_bridge

• fusion_list_documents

• fusion_active_design_summary

• fusion_list_user_parameters

• fusion_list_all_parameters

• fusion_find_entities

• fusion_resolve_entity_token

• fusion_list_bodies

• fusion_list_surface_bodies

• fusion_list_mesh_bodies

• fusion_printability_report

• fusion_list_sketches

• fusion_list_sketch_curves

• fusion_list_sketch_profiles

• fusion_inspect_sketch

• fusion_list_components

• fusion_list_construction_planes

• fusion_list_construction_geometry

• fusion_list_available_appearances

• fusion_list_available_materials

• fusion_list_body_topology

• fusion_inspect_body_physical_properties

• fusion_upsert_user_parameter

• fusion_delete_user_parameter

• fusion_create_rectangle_sketch

• fusion_create_circle_sketch

• fusion_create_line_sketch

• fusion_create_arc_sketch

• fusion_create_ellipse_sketch

• fusion_create_fitted_spline_sketch

• fusion_create_text_sketch

• fusion_create_conic_sketch

• fusion_create_polyline_sketch

• fusion_create_polygon_sketch

• fusion_create_slot_sketch

• fusion_offset_sketch_curves

• fusion_trim_sketch_curve

• fusion_extend_sketch_curve

• fusion_fillet_sketch_curves

• fusion_chamfer_sketch_lines

• fusion_project_entities_to_sketch

• fusion_intersect_entities_with_sketch_plane

• fusion_project_curves_to_surface

• fusion_move_sketch_entities

• fusion_copy_sketch_entities

• fusion_mirror_sketch_entities

• fusion_rectangular_pattern_sketch_entities

• fusion_circular_pattern_sketch_entities

• fusion_add_sketch_constraint

• fusion_add_sketch_dimension

• fusion_set_sketch_dimension_expression

• fusion_delete_sketch_constraint

• fusion_delete_sketch_dimension

• fusion_create_offset_construction_plane

• fusion_create_midplane

• fusion_create_angled_construction_plane

• fusion_create_construction_point_from_sketch_point

• fusion_create_construction_axis_by_two_points

• fusion_create_construction_plane_by_three_points

• fusion_rename_construction_entity

• fusion_delete_construction_entity

• fusion_revolve_profile

• fusion_sweep_profile

• fusion_loft_profiles

• fusion_scale_bodies

• fusion_split_body

• fusion_preview_boundary_fill_cells

• fusion_create_boundary_fill

• fusion_create_silhouette_split

• fusion_merge_faces

• fusion_create_emboss

• fusion_create_derive

• fusion_split_faces

• fusion_delete_faces

• fusion_draft_faces

• fusion_thread_faces

• fusion_thicken_faces

• fusion_replace_faces

• fusion_patch_profile

• fusion_stitch_surface_bodies

• fusion_unstitch_faces

• fusion_extend_surface_edges

• fusion_create_ruled_surface

• fusion_untrim_surface_faces

• fusion_trim_surfaces

• fusion_rename_mesh_body

• fusion_set_mesh_body_visibility

• fusion_set_mesh_body_appearance

• fusion_delete_mesh_body

• fusion_import_mesh

• fusion_convert_mesh_to_brep

• fusion_reduce_mesh

• fusion_repair_mesh

• fusion_combine_mesh_bodies

• fusion_list_sheet_metal_rules

• fusion_create_sheet_metal_rule

• fusion_activate_sheet_metal_rule

• fusion_create_open_hem

• fusion_create_sheet_metal_rip

• fusion_create_box

• fusion_create_plate_with_holes

• fusion_create_printable_svg_plate

• fusion_create_cylinder

• fusion_extrude_profile

• fusion_create_hole

• fusion_fillet_edges

• fusion_chamfer_edges

• fusion_combine_bodies

• fusion_shell_body

• fusion_mirror_bodies

• fusion_rectangular_pattern_bodies

• fusion_circular_pattern_bodies

• fusion_translate_bodies

• fusion_rotate_bodies

• fusion_rename_sketch

• fusion_set_sketch_visibility

• fusion_delete_sketch

• fusion_delete_body

• fusion_set_body_appearance

• fusion_set_face_appearance

• fusion_set_body_material

• fusion_rename_body

• fusion_set_body_visibility

• fusion_rename_construction_plane

• fusion_delete_construction_plane

• fusion_create_component

• fusion_list_component_entities

• fusion_rename_component

• fusion_set_component_visibility

• fusion_activate_component

• fusion_delete_component

• fusion_translate_component

• fusion_create_box_in_component

• fusion_create_cylinder_in_component

• fusion_extrude_component_profile

• fusion_list_assembly_tree

• fusion_list_occurrence_entities

• fusion_list_occurrence_topology

• fusion_create_nested_component

• fusion_move_occurrence_to_component

• fusion_copy_paste_bodies

• fusion_cut_paste_bodies

• fusion_translate_occurrence

• fusion_set_occurrence_grounded

• fusion_create_rigid_group

• fusion_analyze_assembly_interference

• fusion_create_joint

• fusion_create_joint_origin

• fusion_list_joint_origins

• fusion_activate_manufacture_workspace

• fusion_manufacture_status

• fusion_list_cam_setups

• fusion_create_milling_setup

• fusion_list_cam_strategies

• fusion_generate_toolpaths

• fusion_list_cam_parameters

• fusion_set_cam_parameter

• fusion_rename_cam_setup

• fusion_delete_cam_setup

• fusion_rename_cam_operation

• fusion_set_cam_operation_suppression

• fusion_delete_cam_operation

• fusion_list_document_cam_tools

• fusion_list_cam_tool_library

• fusion_create_cam_operation

• fusion_list_cam_post_processors

• fusion_list_nc_programs

• fusion_create_nc_program

• fusion_postprocess_nc_program

• fusion_list_cam_machines

• fusion_assign_cam_machine

• fusion_drawing_status

• fusion_export_drawing_pdf

• fusion_list_workspaces

• fusion_activate_workspace

• fusion_viewport_status

• fusion_set_camera

• fusion_set_viewport_visual_style

• fusion_toggle_mesh_face_groups

• fusion_capture_viewport

• fusion_start_local_render

• fusion_list_render_jobs

• fusion_capture_parameter_animation

• fusion_create_document

• fusion_list_cloud_projects

• fusion_save_document_as

• fusion_activate_document

• fusion_save_document

• fusion_close_document

• fusion_list_timeline

• fusion_rename_timeline_object

• fusion_set_timeline_suppression

• fusion_delete_timeline_object

• fusion_inspect_timeline_dependencies

• fusion_export_step

• fusion_export_stl

• fusion_export_printable_stl

• fusion_import_step

• fusion_export_sketch_dxf

• fusion_import_dxf

• fusion_import_svg

• fusion_export_cad

• fusion_import_cad

• fusion_run_script

Sketch creation tools can work on origin planes (xy, xz, yz) or on a custom construction plane using construction_plane_index.

fusion_find_entities searches bodies, sketches, components, and custom planes by name. It supports exact, contains, and fuzzy, and returns the selector with the index that the other tools expect.

Inspection responses include entityToken when Fusion supports it. fusion_resolve_entity_token lets you recover the entity and its current index after timeline changes.

To add constraints or dimensions, first use fusion_list_sketch_curves and fusion_inspect_sketch; their indices can change after an edit. fusion_list_sketch_profiles lists extrudable profiles with area, centroid, bounding box, and loops; use it to choose profile_indices when a complex SVG or logo generates many regions. fusion_add_sketch_constraint covers horizontal, vertical, parallel, perpendicular, equal, tangent, concentric, collinear, coincident, midpoint, symmetry, smooth, fix, and unfix. fusion_add_sketch_dimension covers length, horizontal, vertical, aligned, angular, diameter, and radius using Fusion expressions; linear dimensions accept a line or two points, and angular requires two lines. Use fusion_set_sketch_dimension_expression to edit a dimension and the fusion_delete_sketch_* tools to delete the selected dimension or constraint.

fusion_save_document saves a new version of a previously saved document. For the first save or to create a copy, use fusion_list_cloud_projects and then fusion_save_document_as with the project_id and the path of an existing folder in Fusion Team.

Timeline tools can affect dependent features and geometry. It is advisable to run fusion_list_timeline before suppressing or deleting an item.

fusion_inspect_body_physical_properties returns mass, density, center of mass, and moments of inertia of a root body. Precision can be low (±1%), medium (±0.5%), high (±0.1%), or very_high (±0.01%); higher precision takes longer. fusion_inspect_timeline_dependencies returns linked features and relationships between parameters associated with the item.

HTTP errors now preserve the detailed message generated inside Fusion. If the bridge is not active, Codex directly indicates how to start FusionCodexBridge. After reinstalling add-in changes, fusion_reload_bridge schedules a bridge restart inside Fusion to load the installed version; if Codex still does not show new tools, restart Codex or reopen the plugin selector to refresh the MCP catalog.

fusion_thread_faces, fusion_thicken_faces, and fusion_replace_faces work with indices obtained from fusion_list_body_topology. Fusion currently does not offer a public API to create Rib/Web; RibFeatures only allows inspecting existing features.

fusion_export_cad and fusion_import_cad support iges, sat, and smt. For DXF, separate tools are used because the format applies to sketches and 2D planes. fusion_export_printable_stl runs basic printability checks before exporting STL of the root component or a specific body, and returns the report along with the generated file. fusion_import_svg imports an SVG into a new sketch on an origin or construction plane, with offset and scale. For a direct printable plate, fusion_create_printable_svg_plate creates a solid rectangular base, imports the SVG onto the top face, and extrudes its profiles as joined relief, separate relief, or cut. In complex SVGs you can use profile_selection (all, largest, area_desc, outer_only) and min_profile_area_cm2 to discard noise; profile_indices remains available for exact manual selection.

Operations inside non-root components cover box, cylinder, and profile extrude. For nested assemblies use fusion_list_assembly_tree: it returns fullPathName, the stable selector consumed by the inspection, creation, movement, and translation tools for nested occurrences. fusion_copy_paste_bodies and fusion_cut_paste_bodies use local indices of the source component; leave the path empty for the root component. Cut/Paste moves bodies and requires allow_move_bodies=true. An occurrence represents a component definition: when that definition has multiple instances, copying or moving bodies can affect all of them; the tool requires additional confirmation before doing so. Before creating a joint use fusion_list_occurrence_topology to get face indices within the context of each occurrence. The MVP of fusion_create_joint supports planar faces and rigid or revolute joints; the second occurrence can be repositioned when creating the joint. fusion_set_occurrence_grounded, fusion_create_rigid_group, and fusion_analyze_assembly_interference work on occurrence paths and the latter does not modify the design.

Surface allows listing surfaces, patch, stitch, unstitch, extend, ruled surface, trim, untrim, and reusing fusion_thicken_faces. In fusion_trim_surfaces, first use selected_cell_indices=[] to get the index preview and then repeat the call with the cells that should be removed.

Mesh allows importing STL/OBJ/3MF, inspecting and managing bodies, assigning appearances, as well as converting, reducing, repairing, and combining. fusion_printability_report checks basic geometric conditions for 3D printing on visible root bodies: solid B-Rep or closed/oriented mesh with positive volume. It serves to detect visual cases such as open meshes with zero volumeCm3, but final validation remains with the slicer. fusion_create_printable_svg_plate returns that report after creating the plate to avoid ending up with geometry that is only visual. The four modification operations use Autodesk preview APIs and may not be available in all installations; in that case the tool returns a guided instruction.

The initial Sheet Metal mapping covers rules, rule activation, open hem, and rip on an existing sheet metal body. Autodesk does not currently expose base flange/flange creation in the public API.

Manufacture allows activating the workspace, inspecting setups/operations/parameters, creating milling setups, editing CAM expressions, renaming/suppressing/deleting items, discovering compatible strategies, and generating toolpaths. It also allows querying document tools or a library tool by URL, creating any strategy compatible with tool and expressions, querying/assigning machines, searching posts, creating NCProgram, and post-processing.

Recommended CAM flow: create or inspect a setup, query fusion_list_cam_strategies, choose a tool with fusion_list_document_cam_tools or fusion_list_cam_tool_library, create the operation with fusion_create_cam_operation, and generate its toolpath. For NC code, discover a machine/post, create the program, and review its index before running fusion_postprocess_nc_program with confirm_postprocess=true. The output directory must exist and final validation of machine, tools, origin, and collisions remains the operator's responsibility.

Drawing allows inspecting the active document/sheet and exporting all sheets or a range to PDF. The public Drawing API does not yet expose a complete collection to programmatically create and edit all sheets, views, and annotations.

Render/Animation includes camera reading and control, viewport visual style control, viewport captures, asynchronous local render, and job tracking. fusion_capture_viewport without output_path returns an inline PNG of up to 20 MiB and deletes the temporary file before finishing; this is the recommended mode for visual inspection. To keep a capture or generate a larger image, pass an explicit output_path and persist=true; for compatibility, old calls that already deliver a path keep persisting. Asynchronous renders and animations still write to the explicit paths indicated by the user. fusion_toggle_mesh_face_groups allows turning off/on the display of mesh face groups when Fusion hides materials and shows face group colors. fusion_capture_parameter_animation interpolates expressions of a parameter, can orbit the camera, writes a PNG sequence, and restores the original parameter/camera; final video assembly is outside Fusion.

fusion_list_workspaces and fusion_activate_workspace allow discovering and activating workspaces by ID. In Simulation this only covers navigation: Autodesk does not currently publish an API model to create and solve studies equivalent to adsk.cam.

fusion_split_body currently uses an origin plane or an existing construction plane as the cutting tool. Later it can be extended to profiles, faces, or bodies as the splitting tool.

For Boundary Fill, first use fusion_preview_boundary_fill_cells with body and/or construction_plane selectors: it returns volume, area, faces, and bounding box of each temporary cell. Then immediately repeat the same selectors, in the same order, with fusion_create_boundary_fill and the selected_cell_indices you want to keep. Those indices are temporary and must not be reused after editing the model. operation accepts new_body, join, cut, or intersect; remove_tool_bodies additionally requires allow_remove_tools=true because it deletes the bodies used as tools.

fusion_create_silhouette_split computes a silhouette split line on a root solid body. The direction accepts a construction_axis, construction_plane, linear edge, or planar face; faces_only is the default non-destructive mode, while shelled_body and solid_body split the body. Fusion limits this feature to compatible bodies; a sphere is a simple case to test the flow.

fusion_merge_faces joins connected faces of the same solid or surface body, but only in a Direct Modeling design. It is a direct B-Rep edit: it does not create a feature or timeline entry, so it requires allow_direct_modification=true. Use is_chain_selection=true to extend a seed face through the compatible connected chain.

fusion_create_emboss maps a sketch profile to a face of a root body. Use positive depth for relief and negative for engraving; expressions accept units or Fusion parameters. The MVP exposes one profile and one face per call, with optional offsets and rotation. It requires the Emboss API introduced by Fusion in September 2025; if not available, it returns a guided indication.

fusion_create_derive creates a derived link from another design document already open and saved in Fusion. Use fusion_list_documents to identify source_document_index; as source entities it accepts root_component, body, mesh_body, sketch, construction_plane, or occurrence. The active document is always the destination and cannot derive from itself. The tool requires the Derive API introduced in January 2026.

fusion_split_faces accepts as tool a body, face, sketch_curve, or construction_plane selector; it supports the surface_intersection, closest_point, and along_vector modes. fusion_delete_faces uses heal by default so Fusion attempts to repair the body. The surface mode deletes without repairing and requires allow_make_surface=true because it can leave an open surface body. All fusion_delete_* tools now require the destination selector and confirm_delete=true; list or inspect the target immediately before confirming. Closing without saving requires save_changes=false and confirm_discard_changes=true.

fusion_draft_faces applies draft on faces of a body using a neutral plane. The usual approach is to use fusion_list_body_topology first to get the face_indices.

Local tests

To run the available unit and contract tests without opening Fusion:

python -m unittest discover -s tests

That suite also verifies that the README tool list, the ROADMAP count, the bridge/plugin/manifest version, and the MCP protocol stay in sync.

For a quick syntax check on the two main Python entrypoints:

python -m py_compile server/main.py fusion_addin/FusionCodexBridge/FusionCodexBridge.py

To run the real 3D printing smoke test against Fusion open with the bridge active:

python .\scripts\smoke_printable_svg.py

That smoke test creates a disposable document, generates a plate from SVG, exports an STL with fusion_export_printable_stl, verifies the file exists, and closes the document without saving. Artifacts remain in scratch/fusion-smoke.

To run a real basic sketches smoke test against Fusion open with the bridge active:

python .\scripts\smoke_sketch_basics.py

That smoke test creates a disposable document, generates rectangle, circle, line, arc, polyline, polygon, and slot sketches, tests offset, constraints, dimensions, and inspection, and closes the document without saving.

Requirements

• Windows with Python 3.10 or later available as python in PATH

• Autodesk Fusion 360

Security configuration

• fusion_run_script is disabled by default. To enable it deliberately, set FUSION_MCP_ENABLE_RUN_SCRIPT=1 for both the MCP process and Fusion 360, and restart both. The script runs with the user's full permissions, so dedicated tools should be preferred.

• FUSION_MCP_MAX_REQUEST_BODY_BYTES adjusts the limit for bridge JSON payloads. The default value is 1 MiB and the maximum accepted is 16 MiB.

• Delete operations, discarding changes, and post-processing require their explicit confirmation flags; those flags do not replace prior inspection of the target.

Recommended installation on Windows

If you already have this repository locally, the fastest way to install it is:

powershell -ExecutionPolicy Bypass -File .\scripts\install-fusion-mcp.ps1

That installer does the following:

• generates or keeps a random private credential to authenticate MCP with Fusion

• protects the credential file and, when it creates its dedicated folder, also restricts that folder's permissions to the current user; it does not alter the ACLs of a pre-existing parent folder

• builds the plugin from an allowed file list and copies it to ~/plugins/fusion-mcp, without including captures, backups, CAD, or other workspace artifacts

• validates by manifest the plugin and add-in destinations; rejects overlaps with the repository, unrecognized folders, junctions, and state files inside managed destinations

• publishes the runtime via candidate + backup and restores the previous version if the marketplace fails

• updates ~/.agents/plugins/marketplace.json via an atomic replacement after publishing the runtime

• installs the requirements.txt dependencies

• copies the Fusion add-in to %APPDATA%\Autodesk\Autodesk Fusion 360\API\AddIns\FusionCodexBridge if that folder exists; otherwise it uses %APPDATA%\Autodesk\Autodesk Fusion\API\AddIns\FusionCodexBridge

• syncs those installation folders and removes stale files from previous versions

• warns if it finds another copy of FusionCodexBridge in the alternative Autodesk path, because Fusion could be loading an old copy

If you only want to install the Codex part and not copy the Fusion add-in yet, you can use:

powershell -ExecutionPolicy Bypass -File .\scripts\install-fusion-mcp.ps1 -SkipFusionAddIn

Step by step to get it working

1. Open a terminal at the repository root.

2. Run the installer:

   powershell -ExecutionPolicy Bypass -File .\scripts\install-fusion-mcp.ps1

3. Open Fusion 360.

4. In Fusion, go to Utilities > Add-Ins > Scripts and Add-Ins.

5. Go to the Add-Ins tab.

6. If the list appears empty, clear the filters before assuming the add-in is missing.

7. Look for FusionCodexBridge and run it with Run.

8. If FusionCodexBridge does not appear in the list, use the + button and manually point to one of these folders:

   • %APPDATA%\Autodesk\Autodesk Fusion 360\API\AddIns\FusionCodexBridge

   • %APPDATA%\Autodesk\Autodesk Fusion\API\AddIns\FusionCodexBridge

9. Verify that the local Fusion bridge is running:

   $credential = Get-Content "$env:LOCALAPPDATA\FusionMCP\credentials.json" -Raw | ConvertFrom-Json
   Invoke-RestMethod http://127.0.0.1:19851/health -Headers @{ Authorization = "Bearer $($credential.token)" }

   You should receive a JSON response with "ok": true.

10. Restart Codex or reload the VS Code window if needed.

11. If you use Codex CLI or the Codex app, register the MCP server once:

codex mcp add fusion-local -- python "$HOME\plugins\fusion-mcp\server\main.py"

12. Check that the server was registered:

codex mcp list

13. Go back to Codex and try a simple instruction, for example:

• review the active design in Fusion

• run a fusion_status

• create a 10x6x3 cm box

Manual installation

Manual installation also requires MCP and Fusion to share a token of at least 32 characters via FUSION_MCP_TOKEN or a JSON file specified by FUSION_MCP_CREDENTIALS_FILE. To avoid permission and configuration errors, it is recommended to run the installer at least once.

If you do not want to use the installer, you can do the process by hand:

1. Install the Python dependencies:

   pip install -r requirements.txt

2. Copy fusion_addin/FusionCodexBridge/ to a Fusion Add-Ins folder:

   • %APPDATA%\Autodesk\Autodesk Fusion 360\API\AddIns\

   • or %APPDATA%\Autodesk\Autodesk Fusion\API\AddIns\

3. Register the MCP server in Codex:

   codex mcp add fusion-local -- python "$PWD\server\main.py"

4. Open Fusion 360 and run FusionCodexBridge from Utilities > Add-Ins > Scripts and Add-Ins.

Troubleshooting

• If Fusion shows an empty add-ins list, first clear the filters in the Scripts and Add-Ins window.

• If VS Code shows No MCP Servers found, run Developer: Reload Window and then use MCP: List Servers again.

• Do not search for fusion-local in the VS Code extensions Marketplace. It is a local MCP server, not a marketplace extension.

• If Codex sees the server but actions against Fusion fail, use the /health check command above or run fusion_ping; all endpoints require the local Bearer token.

• If Codex reports that the bridge is incompatible or protocolVersion is missing, run powershell -ExecutionPolicy Bypass -File .\scripts\install-fusion-mcp.ps1 and then fusion_reload_bridge or restart Fusion.

• If the installer warns that another copy of FusionCodexBridge exists, open Scripts and Add-Ins and confirm that you are running the updated folder that the installer printed.

• If you receive Unauthorized Fusion MCP request, run the installer again and restart Codex and the add-in so that both use the same credential.

• If the installer rejects an existing credentials file, check that CredentialPath is correct. To regenerate a truly corrupted credential, explicitly move or delete that file and run the installer again; the installer does not overwrite unknown files.

• Do not copy or publish %LOCALAPPDATA%\FusionMCP\credentials.json; the installer never displays the token.

Notes

• fusion_run_script runs Python inside Fusion with full API access and is disabled by default. Use it only with trusted code and through explicit opt-in.

• All endpoints, including /health, require the Bearer token generated during installation.

• The script tool returns the value assigned to the result variable.

• If the bridge is not running, start by testing with fusion_ping or fusion_status after starting the add-in.