FreeCAD MCP for Windsurf: Setup & Config

What you can do with FreeCAD in Windsurf

Choose direct FreeCAD modeling with library parts, Python access, screenshots, and existing-analysis FEM runs.

• Inspect a model through object data and active-view screenshots.
• Run an existing FEM analysis and review its summary results.

Before you start: FreeCAD in Windsurf

• FreeCAD
• The FreeCADMCP addon installed in the appropriate addon directory
• uvx
• Claude Desktop for the documented client setup

Restart FreeCAD after installing the addon, choose the MCP Addon workbench, and start its RPC server. --only-text-feedback disables visual feedback. Remote RPC access requires explicit enablement and allowed IPs.

FreeCAD Windsurf configuration

1. Choose Windsurf configuration scope

   For FreeCAD MCP, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add FreeCAD MCP to Windsurf

   Use the freecad-mcp entry below in mcpServers. Keep FreeCAD MCP's documented stdio connection fields and your other Windsurf entries.

3. Check FreeCAD MCP in Windsurf

   FreeCAD MCP: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "freecad-mcp": {
      "command": "uvx",
      "args": [
        "freecad-mcp"
      ],
      "env": {}
    }
  }
}

FreeCAD tools available to Windsurf

FreeCAD's stored tool list documents 11 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

create_document

After refreshing FreeCAD in Windsurf settings, check Cascade's tool list for create_document.

Start a new CAD document in FreeCAD.

create_object

After refreshing FreeCAD in Windsurf settings, check Cascade's tool list for create_object.

Add a CAD object to a FreeCAD document.

edit_object

After refreshing FreeCAD in Windsurf settings, check Cascade's tool list for edit_object.

delete_object

After refreshing FreeCAD in Windsurf settings, check Cascade's tool list for delete_object.

execute_code

After refreshing FreeCAD in Windsurf settings, check Cascade's tool list for execute_code.

Run arbitrary Python within the FreeCAD application.

insert_part_from_library

After refreshing FreeCAD in Windsurf settings, check Cascade's tool list for insert_part_from_library.

Insert a reusable component from the FreeCAD parts library.

get_view

After refreshing FreeCAD in Windsurf settings, check Cascade's tool list for get_view.

get_objects

After refreshing FreeCAD in Windsurf settings, check Cascade's tool list for get_objects.

get_object

After refreshing FreeCAD in Windsurf settings, check Cascade's tool list for get_object.

get_parts_list

After refreshing FreeCAD in Windsurf settings, check Cascade's tool list for get_parts_list.

List available components in the FreeCAD parts library.

run_fem_analysis

After refreshing FreeCAD in Windsurf settings, check Cascade's tool list for run_fem_analysis.

Run CalculiX for an existing FEM analysis and report stress, displacement, node count, and working directory.

FreeCAD: full stored tool descriptions

Troubleshooting FreeCAD in Windsurf

• Check uvx freecad-mcp (from uv, for Python tools) on the machine running Windsurf's MCP integration for FreeCAD MCP; refresh MCP and inspect Cascade's tools.
• FreeCAD MCP uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires a FreeCAD addon plus a running RPC server.
• Known limitation: The Python execution tool can run arbitrary code inside FreeCAD.
• Known limitation: Remote access requires explicit IP allowlisting and RPC configuration.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions