Noureddine RAMDI / freecad-mcp: bridging AI and parametric CAD through an MCP server

Created Mon, 04 May 2026 10:23:02 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
819 Words
github-stars python freecad mcp rpc cad ai-integration

neka-nat/freecad-mcp

freecad-mcp is a Python-based MCP server addon for FreeCAD that opens a programmable interface for AI-driven parametric CAD modeling. By exposing FreeCAD’s functionality through an RPC server, it allows an AI client—specifically Claude Desktop—to remotely create, edit, and manage CAD objects. The most striking feature is the ability to execute arbitrary Python code inside FreeCAD from the AI client, providing comprehensive programmatic control over the CAD kernel.

bridging AI and FreeCAD with an MCP server

At its core, freecad-mcp implements the Model Context Protocol (MCP) to connect an AI agent with FreeCAD’s parametric modeling environment. The repo is structured as a FreeCAD addon, written in Python, that installs into FreeCAD’s Mod directory. Once loaded, it spins up an RPC server exposing a set of MCP tools mapped to FreeCAD operations.

The architecture is a two-tier model:

  • FreeCAD side: Runs the MCP server inside FreeCAD as an addon. It listens for RPC calls and translates MCP tool invocations into FreeCAD Python API calls.
  • Client side: Claude Desktop MCP client connects to this server, sending commands formatted as MCP tool calls defined in a JSON configuration.

This design allows remote AI-driven manipulation of CAD models with tools covering object creation, modification, deletion, arbitrary Python code execution, screenshots, and parts library access. The server supports remote connections with IP allowlisting and token-based authentication for security. It also includes features like auto-start persistence and a feedback mode that saves textual interaction logs.

the execute_code tool: power and caution

The standout capability is the execute_code tool. This tool enables the MCP client to send arbitrary Python code snippets to be run inside FreeCAD’s Python interpreter. This means the AI client can:

  • Perform any operation supported by FreeCAD’s Python API
  • Automate complex parametric modeling workflows beyond predefined commands
  • Query and manipulate the internal state of the CAD document

While this unlocks immense flexibility and the potential for generative design workflows, it comes with significant tradeoffs:

  • Security risk: Running arbitrary code remotely is inherently risky. The current implementation relies on IP allowlisting and token authentication, but there is no sandboxing or code sanitization. If exposed, this interface could be exploited to execute malicious code.
  • Error handling: FreeCAD’s Python API calls can raise exceptions. The MCP server must gracefully catch and report errors back to the client, which the repo handles but with some limitations in robustness.
  • Complexity for users: Interacting with the full FreeCAD Python API requires familiarity with FreeCAD scripting. While the AI client generates code, debugging or extending the system manually may require CAD scripting knowledge.

Mapping FreeCAD’s API into MCP tool schemas is done selectively across nine tools, balancing between specific operations (create/edit/delete objects) and generic code execution. This layered approach gives users and AI clients both convenience and deep control.

install and get started with freecad-mcp

The installation is straightforward but requires manual placement of the addon directory in FreeCAD’s Mod folder appropriate to your OS:

FreeCAD Addon directory is

  • Windows: %APPDATA%\FreeCAD\Mod\
  • Mac:
    • FreeCAD 1.1: ~/Library/Application\ Support/FreeCAD/v1-1/Mod/
    • FreeCAD 1.0: ~/Library/Application\ Support/FreeCAD/v1-0/Mod/
  • Linux:
    • Ubuntu: ~/.FreeCAD/Mod/ or ~/snap/freecad/common/Mod/ (if installed from snap)
    • Debian: ~/.local/share/FreeCAD/Mod
    • Arch / CachyOS (FreeCAD 1.1 from extra/freecad): ~/.local/share/FreeCAD/v1-1/Mod/

Please put addon/FreeCADMCP directory to the addon directory.

git clone https://github.com/neka-nat/freecad-mcp.git
cd freecad-mcp

After placing the addon, start FreeCAD and enable the MCP addon. The MCP server will start and listen for connections from the Claude Desktop client configured per JSON.

This setup allows you to experiment with AI-driven parametric CAD automation, with the usual caveats around security and stability.

verdict: a powerful bridge for AI-assisted CAD with caveats

freecad-mcp is a solid technical demonstration of how MCP can extend AI agents into desktop CAD applications for generative design workflows. It exposes FreeCAD’s powerful parametric modeling capabilities through a standardized RPC interface that an AI client can command.

The ability to execute arbitrary Python code inside FreeCAD is the repo’s strongest and riskiest feature—offering unmatched flexibility at the cost of potential security vulnerabilities. This means it suits research, prototyping, and controlled environments rather than production CAD workflows out of the box.

If you work at the intersection of AI and CAD, or you want to explore programmatic CAD automation driven by LLMs like Claude, this repo is worth studying. However, its limitations around security, error handling, and user expertise requirements mean caution and further development are needed before deploying in sensitive or commercial settings.

Overall, freecad-mcp is a practical, hands-on example of layered AI integration with a complex desktop app, worthy of attention from developers pushing AI-assisted design boundaries.

→ GitHub Repo: neka-nat/freecad-mcp ⭐ 881 · Python