freecad_mcp

The FreeCAD MCP server exposes a lightweight socket-based interface that lets you query information about the current FreeCAD document and execute Python scripts within FreeCAD's context. The primary commands exposed are get_scene_info, which returns document properties, object data, sketch details, and view/camera information, and run_script, which executes arbitrary Python code inside FreeCAD and returns the results. To use it, connect to the server (default host is localhost and the port configured by the bridging script, often 9876) and send a JSON payload with a type field specifying the command (for example, {"type": "get_scene_info"} or {"type": "run_script", "params": {"script": "# your python code here"}}). The server will respond with a JSON payload containing the requested information or the output of the executed script. This enables automation, batch processing, and integration with external tooling that needs to inspect or modify FreeCAD documents remotely.

Typical workflows include retrieving scene information to generate reports or visualizations, and programmatically constructing or modifying geometry by sending Python scripts that interact with FreeCAD's API (e.g., creating parts, setting dimensions, or updating the active document).

Prerequisites:

• A working FreeCAD installation with the FreeCAD MCP module available (as described in the repository).
• Python installed (matching your FreeCAD environment, e.g., Python from Anaconda or system Python).
• Access to the FreeCAD MCP bridge script (freecad_bridge.py) and the MCP module directory (freecad_mcp).

Install steps:

1. Install FreeCAD and ensure the MCP module (freecad_mcp) is placed in your FreeCAD modules directory:
   • Windows: %APPDATA%/FreeCAD/Mod/
   • Linux: ~/.FreeCAD/Mod/
   • macOS: ~/Library/Preferences/FreeCAD/Mod/
2. Place the freecad_mcp directory in the appropriate FreeCAD Mod directory and restart FreeCAD.
3. Ensure the Python environment referenced by the MCP server can import FreeCAD modules. If using a separate Python interpreter, install or point to the Python executable that has access to FreeCAD Python bindings.
4. Create the mcp configuration file (e.g., mcp_config.json) with the required structure, pointing to the correct Python executable and the freecad_bridge.py script: { "mcpServers": { "freecad": { "command": "C:\ProgramData\anaconda3\python.exe", "args": [ "C:\Users\USER\AppData\Roaming\FreeCAD\Mod\freecad_mcp\src\freecad_bridge.py" ] } } }
5. Start FreeCAD and ensure the MCP bridge is loaded, then run your client script to connect to the MCP server at localhost:9876 (or the configured port).
6. Verify connectivity by sending a get_scene_info request before attempting run_script operations.

Notes and tips:

• Ensure the paths in the mcp_config.json match your actual system paths for Python and freecad_bridge.py. Adjust for Windows, Linux, or macOS as needed.
• If FreeCAD is launched in a different user context, ensure the MCP bridge script has access to the FreeCAD session and its active document.
• When running scripts via run_script, consider sandboxing or limiting the code to avoid unintended changes to the FreeCAD document. Always test on a copy of the document.
• If the MCP bridge cannot connect, check firewall rules and that FreeCAD is not blocked from socket connections. Verify that the port (default 9876) is not used by another process.
• Use get_scene_info to inspect the current document state before performing automated edits to ensure you are operating on the expected document and objects.
• If you need to run this in a headless environment, ensure FreeCAD can operate in headless mode or that a GUI session is available for the FreeCAD process.