# FreeCAD MCP (pypi · freecad-mcp)

Control FreeCAD from MCP clients: create and edit models, run Python and FEM analyses.

- Trust score: 59/100 (low)
- Change this week: 0
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-11-21

## Components

- pypi · `freecad-mcp`: 59/100 (this document), [markdown](https://verifymcp.io/servers/neka-nat-freecad-mcp/freecad-mcp.md), [page](https://verifymcp.io/servers/neka-nat-freecad-mcp/freecad-mcp)

## Channel facts

- Registry: `pypi`
- Package: `freecad-mcp`
- Version: `0.1.31`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-11-21.

- **Supply Chain Security**: 100/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - Runs hatchling.build at install time, a recognised build step with no custom scripting around it.
  - 1 of 30 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 4 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 36/100
  - 0% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 4715 tokens (~277/item across 17 items; 17 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 67/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 0% of tool parameters carry a description.
- **Tool Safety**: 75/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - 0 of 4 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "delete_object" implies "delete" and declares no destructiveHint at all, which the MCP spec reads as destructive by default.
  - An AI judge read all 18 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a current MCP spec version (2026-07-28).

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### How do I install the FreeCAD MCP server?

FreeCAD MCP runs locally as a PyPI package, launched with uvx freecad-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add neka-nat-freecad-mcp -- uvx freecad-mcp
```

### Cursor

```json
{
  "mcpServers": {
    "neka-nat-freecad-mcp": {
      "command": "uvx",
      "args": [
        "freecad-mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "neka-nat-freecad-mcp": {
      "command": "uvx",
      "args": [
        "freecad-mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add neka-nat-freecad-mcp -- uvx freecad-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "neka-nat-freecad-mcp": {
      "type": "local",
      "command": [
        "uvx",
        "freecad-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add neka-nat-freecad-mcp --command uvx --arg freecad-mcp
```

### Hermes

```yaml
mcp_servers:
  neka-nat-freecad-mcp:
    command: "uvx"
    args: ["freecad-mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "neka-nat-freecad-mcp": {
      "Transport": "stdio",
      "Command": "uvx",
      "Arguments": [
        "freecad-mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add neka-nat-freecad-mcp -t stdio -c uvx -a freecad-mcp
```

### Other

```json
{
  "mcpServers": {
    "neka-nat-freecad-mcp": {
      "command": "uvx",
      "args": [
        "freecad-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-11-21 (score 59, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-11-20 (score 44, −15)

- [security regression] Malware scan: pass → unverified

### 2026-11-19 (score 59, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-11-18 (score 44, −15)

- [security regression] Malware scan: pass → unverified

### 2026-11-17 (score 59, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-11-16 (score 44, −15)

- [security regression] Malware scan: pass → unverified

### 2026-11-14 (score 59, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-11-12 (score 44)

First indexed and scored.

## MCP tools (17)

### `create_document` (~92 tokens)

Create a new document in FreeCAD.

Args:
    name: The name of the document to create.

Returns:
    A message indicating the success or failure of the document creation.

Examples:
    If you want to create a document named "MyDocument", you can use the following data.
    ```json
    {
        "name": "MyDocument"
    }
    ```

Input parameters:

- `name` (string, required)

### `create_object` (~1308 tokens)

Create a new object in FreeCAD.

\``obj_type`` must name a type registered in FreeCAD's C++ type system, such
as "Part::", "PartDesign::" or "Fem::" types. A number of FreeCAD features
are implemented in Python rather than C++ and so are not registered types;
of those, these are supported here through dedicated factories, and each
requires the properties listed beside it:

    Part::Tube        InnerRadius, OuterRadius, Height
    Draft::Circle     Radius
    Draft::Rectangle  Length, Height
    Draft::Polygon    FacesNumber, Radius
    Draft::Wire       Points (list of {x, y, z}), optional Closed

Any other Python-implemented type (Draft::Point, Draft::Ellipse, ...) must
be built with ``execute_code`` instead.

Note that the Draft factories name objects themselves, so for those the
returned object_name will differ from the requested obj_name, which is
applied to the object's Label instead. Always use the returned name in
later get_object/edit_object calls.

Args:
    doc_name: The name of the document to create the object in.
    obj_type: The type of the object to create (e.g. 'Part::Box', 'Part::Cylinder', 'Part::Cut', 'PartDesign::Body', etc.).
    obj_name: The name of the object to create.
    obj_properties: The properties of the object to create.
    include_screenshot: Whether to return a screenshot of the model (default True).
        Set to False to save tokens when visual feedback is not needed,
        e.g. for intermediate steps in a longer sequence of changes.
    view_name: The view orientation of the returned screenshot (default "Isometric").
        Pick the view that best shows the change being made.

Returns:
    A message indicating the success or failure of the object creation and a screenshot of the object.

Examples:
    If you want to create a cylinder with a height of 30 and a radius of 10, you can use the following data.
    ```json
    {
        "doc_name": "MyCylinder",
        "obj_name": "Cylinder",
        "obj_type": "Part::Cylinder"…

Input parameters:

- `analysis_name`
- `doc_name` (string, required)
- `include_screenshot` (boolean)
- `obj_name` (string, required)
- `obj_properties`
- `obj_type` (string, required)
- `view_name` (string)

### `edit_object` (~209 tokens)

Edit an object in FreeCAD.
This tool is used when the `create_object` tool cannot handle the object creation.

Args:
    doc_name: The name of the document to edit the object in.
    obj_name: The name of the object to edit.
    obj_properties: The properties of the object to edit.
    include_screenshot: Whether to return a screenshot of the model (default True).
        Set to False to save tokens when visual feedback is not needed,
        e.g. for intermediate steps in a longer sequence of changes.
    view_name: The view orientation of the returned screenshot (default "Isometric").
        Pick the view that best shows the change being made.

Returns:
    A message indicating the success or failure of the object editing and a screenshot of the object.

Input parameters:

- `doc_name` (string, required)
- `include_screenshot` (boolean)
- `obj_name` (string, required)
- `obj_properties` (object, required)
- `view_name` (string)

### `delete_object` (~172 tokens)

Delete an object in FreeCAD.

Args:
    doc_name: The name of the document to delete the object from.
    obj_name: The name of the object to delete.
    include_screenshot: Whether to return a screenshot of the model (default True).
        Set to False to save tokens when visual feedback is not needed,
        e.g. for intermediate steps in a longer sequence of changes.
    view_name: The view orientation of the returned screenshot (default "Isometric").
        Pick the view that best shows the change being made.

Returns:
    A message indicating the success or failure of the object deletion and a screenshot of the object.

Input parameters:

- `doc_name` (string, required)
- `include_screenshot` (boolean)
- `obj_name` (string, required)
- `view_name` (string)

### `execute_code_async` (~572 tokens)

Execute Python code in FreeCAD without waiting for completion.

Use this ONLY for long-running background computations that do NOT touch the
FreeCAD GUI or mutate the FreeCAD document tree directly.

This tool runs the submitted code in a background thread and returns
immediately. Because it does not run on FreeCAD's main GUI thread, the code
must NOT directly call FreeCADGui APIs, manipulate the active view or
selection, create or edit document objects, change object properties, call
doc.recompute(), or save documents. FreeCAD documents and the Coin3D
scenegraph are not thread-safe: writing to them from this thread races the
GUI thread and can wedge FreeCAD's event loop, after which the RPC server
stops responding entirely and FreeCAD must be restarted.

Every document or view write must instead be handed to the GUI thread through
the injected commit() helper:

    commit(fn, timeout=120) -> fn's return value

Scripts share a live namespace. Saved functions can use commit() in later
async calls; calling it from execute_code or a GUI callback raises immediately.
Coordinate concurrent scripts that intentionally modify the same variables.

commit() queues fn on the GUI thread, waits for it, and raises RuntimeError if
dispatch fails or times out. Example:

    fused = base.fuse(addition).removeSplitter()   # slow, safe in background

    def apply():                                   # runs on the GUI thread
        obj.Shape = fused
        doc.recompute()

    commit(apply)

For code that is not dominated by heavy geometry computation, use execute_code
instead. execute_code runs entirely on the FreeCAD GUI thread and is the safe
default for normal FreeCAD automation.

Use execute_code_async only when the heavy part is long-running OCCT geometry
(e.g. fuse/cut/loft on already-fetched shapes) or other CPU-bound computation
that would exceed execute_code's 90 s GUI-thread budget.

Typical usage pattern:
1\. Fetch shapes into module-level variables first (via execute_cod…

Input parameters:

- `code` (string, required)

### `execute_code_headless` (~293 tokens)

Run a FreeCAD Python script in a separate headless `freecadcmd` process.

Use this for OCCT work that can crash or block FreeCAD: helical threads
(makeHelix + makePipeShell), lofts and sweeps, booleans with many or
B-spline tools, long parametric rebuilds. A native OpenCascade crash
here only kills the helper process; the GUI and its open documents
survive, and the tool reports the crash signal and the script's output.

The script runs on the MCP server machine, independently of --host, in a
fresh process without GUI: import FreeCAD/Part
yourself, open documents from disk (FreeCAD.openDocument(path)), save
results with doc.save()/saveAs() or Shape.exportBrep(). Nothing from the
execute_code namespace is available. Print progress to stdout; it is
returned when the process ends. After the script saved a .FCStd that is
open in the GUI, call reload_document(doc_name) to show the result.

Args:
    code: Complete Python script for freecadcmd.
    timeout: Positive finite seconds to wait before killing the process
        (default 600). Partial output is preserved on timeout.

Returns:
    Exit status, crash/timeout diagnosis and the script's printed output.

Input parameters:

- `code` (string, required)
- `timeout` (number)

### `get_async_status` (~113 tokens)

Report the state of background jobs started by execute_code_async.

Does not use the FreeCAD GUI thread, so it answers even while a job runs.

Args:
    job_id: The id returned by execute_code_async. Empty lists all running
        jobs and up to 20 recently completed jobs.

Returns:
    For one job: its state (running/done/failed), the error and traceback
    when it failed. History is held in memory until FreeCAD exits.

Input parameters:

- `job_id` (string)

### `execute_code` (~288 tokens)

Execute arbitrary Python code in FreeCAD.

Args:
    code: The Python code to execute.
    include_screenshot: Whether to return a screenshot of the model (default True).
        Set to False to save tokens when the code does not change the model's
        appearance, e.g. analytical or computational scripts whose result is
        printed output, or intermediate steps in a longer sequence of changes.
    view_name: The view orientation of the returned screenshot (default "Isometric").
        Pick the view that best shows the change being made.
    timeout: Positive finite seconds for each of the queue and GUI execution
        budgets, overriding the 90 s default for this call (capped at 1800).
        Raise it for slow work that must
        run on the GUI thread, such as importing or exporting a large STEP
        assembly. Without it the call reports a timeout while the task keeps
        running, and the result is lost even though the work finishes. Prefer
        execute_code_async for heavy pure-geometry work that touches neither
        the document nor the GUI.

Returns:
    A message indicating the success or failure of the code execution, the output of the code execution, and a screenshot of the object.

Input parameters:

- `code` (string, required)
- `include_screenshot` (boolean)
- `timeout`
- `view_name` (string)

### `get_view` (~187 tokens)

Get a screenshot of the active view.

Args:
    view_name: The name of the view to get the screenshot of.
    The following views are available:
    - "Isometric"
    - "Front"
    - "Top"
    - "Right"
    - "Back"
    - "Left"
    - "Bottom"
    - "Dimetric"
    - "Trimetric"
    width: The width of the screenshot in pixels. If not specified, uses the viewport width.
    height: The height of the screenshot in pixels. If not specified, uses the viewport height.
    focus_object: The name of the object to focus on. If not specified, fits all objects in the view.

Returns:
    A screenshot of the active view.

Input parameters:

- `focus_object`
- `height`
- `view_name` (string, required)
- `width`

### `insert_part_from_library` (~154 tokens)

Insert a part from the parts library addon.

Args:
    relative_path: The relative path of the part to insert.
    include_screenshot: Whether to return a screenshot of the model (default True).
        Set to False to save tokens when visual feedback is not needed,
        e.g. for intermediate steps in a longer sequence of changes.
    view_name: The view orientation of the returned screenshot (default "Isometric").
        Pick the view that best shows the change being made.

Returns:
    A message indicating the success or failure of the part insertion and a screenshot of the object.

Input parameters:

- `include_screenshot` (boolean)
- `relative_path` (string, required)
- `view_name` (string)

### `get_objects` (~144 tokens)

Get all objects in a document.
You can use this tool to get the objects in a document to see what you can check or edit.

Args:
    doc_name: The name of the document to get the objects from.
    include_screenshot: Whether to return a screenshot of the document (default True).
        Set to False to save tokens when only the object data is needed.
    view_name: The view orientation of the returned screenshot (default "Isometric").

Returns:
    A list of objects in the document and a screenshot of the document.

Input parameters:

- `doc_name` (string, required)
- `include_screenshot` (boolean)
- `view_name` (string)

### `get_object` (~159 tokens)

Get an object from a document.
You can use this tool to get the properties of an object to see what you can check or edit.

Args:
    doc_name: The name of the document to get the object from.
    obj_name: The name of the object to get.
    include_screenshot: Whether to return a screenshot of the document (default True).
        Set to False to save tokens when only the object data is needed.
    view_name: The view orientation of the returned screenshot (default "Isometric").

Returns:
    The object and a screenshot of the object.

Input parameters:

- `doc_name` (string, required)
- `include_screenshot` (boolean)
- `obj_name` (string, required)
- `view_name` (string)

### `get_parts_list` (~21 tokens)

Get the list of parts in the parts library addon.

### `reload_document` (~253 tokens)

Close and re-open a document to pick up external file changes.

Use this AFTER the document's .FCStd file has been modified by
something outside of FreeCAD's GUI process — for example, a
headless `freecadcmd` script that edited and saved the file. The
open GUI document is otherwise unaware of on-disk changes; this
tool closes the stale in-memory copy and reopens the file from
disk so the GUI shows current geometry.

Args:
    doc_name: The name of the open document to reload. Must match
        the name shown by ``list_documents``.

Returns:
    A message confirming the document was reloaded, or describing
    the failure (document not loaded, no associated file, etc).
    FreeCAD names the reopened document after the file stem, which
    can differ from ``doc_name`` ("HandleConcept3D" saved as
    handle-concept-3d.FCStd reopens as handle_concept_3d); the reply
    names the document you should use from then on.

Examples:
    ```json
    {
        "doc_name": "chassis"
    }
    ```

Input parameters:

- `doc_name` (string, required)

### `list_documents` (~27 tokens)

Get the list of open documents in FreeCAD.

Returns:
    A list of document names.

### `get_rpc_status` (~88 tokens)

Get RPC and FreeCAD GUI-dispatch health.

This tool does not use FreeCAD's GUI thread, so it remains available after
a GUI operation times out. A ``stuck`` state identifies the operation that
is still running and indicates that FreeCAD may need to be restarted.
\``version_check`` is "ok" or says whether the addon or the server needs
updating.

### `run_fem_analysis` (~623 tokens)

Run the CalculiX solver on an existing Fem::FemAnalysis container and return summary results.

Prerequisites in the document, all created with `create_object`:
\- A Part-derived solid (e.g. Part::Box, PartDesign::Body) acting as the geometry.
\- A Fem::AnalysisPython container.
\- A material: type "Fem::MaterialCommon" with analysis_name set (built with
  ObjectsFem.makeMaterialSolid) and its Material given as a dict with units,
  e.g. {"Name": "Steel", "YoungsModulus": "210 GPa", "PoissonRatio": "0.3",
  "Density": "7900 kg/m^3"}. A dict read from the material library can
  come back empty; give the values.
\- A mesh: type "Fem::FemMeshGmsh" with analysis_name, Shape (the geometry)
  and CharacteristicLengthMax / CharacteristicLengthMin; it is generated
  when created. A section needs several elements across its thickness,
  or bending stress comes out far too low.
\- At least one Fem::ConstraintFixed and one Fem::ConstraintForce (or
  ConstraintPressure) whose References are faces of the geometry.
\- Set Force with its unit, e.g. "1000 N": create_object/edit_object reject
  unitless values. In existing documents and execute_code, a plain number
  uses millinewtons, so Force = 1000 applies 1 N. The force acts along the
  normal of the loaded face unless Direction links an edge or face;
  Reversed flips it.

A SolverCcxTools is auto-created if the analysis has none. The reply
lists mechanical loads captured in the same GUI operation as the solve
(in N and MPa, with faces and direction). A failed load read stops the solve.
Direction can be set to {"object_name": "Beam", "edge": "Edge1"}.

The solver runs synchronously on the FreeCAD GUI thread and blocks all
other RPC calls for its duration; do not fan out parallel requests.

Returns max von Mises stress (MPa), max/min displacement (mm), node count,
and the working directory CalculiX wrote to. On failure, returns the
prerequisite-check or solver error along with the working directory for
triage.

Args:
    doc_name: Name…

Input parameters:

- `analysis_name` (string, required)
- `doc_name` (string, required)
- `include_screenshot` (boolean)
- `timeout` (integer)
- `view_name` (string)

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/neka-nat-freecad-mcp/freecad-mcp#diagnostics

## Score history

- 2026-11-21: 59
- 2026-11-20: 44
- 2026-11-19: 59
- 2026-11-18: 44
- 2026-11-17: 59
- 2026-11-16: 44
- 2026-11-15: 59
- 2026-11-14: 59
- 2026-11-13: 44
- 2026-11-12: 44

## Common questions

### What is the FreeCAD MCP server?

FreeCAD MCP is listed in the public MCP registry as io.github.neka-nat/freecad-mcp. Control FreeCAD from MCP clients: create and edit models, run Python and FEM analyses. This page covers its PyPI package (freecad-mcp).

### Is the FreeCAD MCP server safe to use?

FreeCAD MCP scores 59 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 21 November 2026. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the FreeCAD MCP server expose?

FreeCAD MCP exposes 17 tools: create_document, create_object, edit_object, delete_object, execute_code_async, and 12 more. Their descriptions and schemas cost roughly 4,703 tokens of context every time the server is loaded.

### Is the FreeCAD MCP server still maintained?

FreeCAD MCP is still listed as active in the MCP registry. We last reached this channel on 21 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the FreeCAD MCP server under?

FreeCAD MCP declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

### What did VerifyMCP test on the FreeCAD MCP server?

VerifyMCP ran 15 checks on FreeCAD MCP, covering Malware scan, Known CVEs, Install scripts, Dependency health and 11 more. One item could not be completed, a gap on our side rather than a finding about FreeCAD MCP: Stability. One category scores 0 for that reason, because we only credit what we can confirm. Endpoint Security and Transport & Reachability do not apply to a PyPI package, so they were not tested. The score does not measure everything, and the scoring documentation lists what it leaves out.

## Links

- PyPI project: https://pypi.org/project/freecad-mcp/
- Socket report: https://socket.dev/pypi/package/freecad-mcp
- Repository: https://github.com/neka-nat/freecad-mcp
- Changelog RSS feed: https://verifymcp.io/servers/neka-nat-freecad-mcp/freecad-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/neka-nat-freecad-mcp/freecad-mcp/changelog.json
- Trust report (JSON): https://verifymcp.io/servers/neka-nat-freecad-mcp/freecad-mcp.json
- HTML version of this page: https://verifymcp.io/servers/neka-nat-freecad-mcp/freecad-mcp
