Skip to main content
Glama
Sign In
enesjakozh

mcp-freecad

by jango-blockchained
Verified
GitHub
Python
MIT License
4
  • Linux
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

local-only server

The server can only run on the client’s local machine because it depends on local resources.

Integrations

  • Enables interaction with FreeCAD CAD software through a standardized interface, offering tools for 3D model creation, manipulation, measurement, and export. Includes specialized smithery tools for blacksmithing designs, primitive shape generation, boolean operations, and model transformation capabilities.

🛠️ MCP-FreeCAD 集成

**注意：**此仓库正在大力开发中。预计每天都会有提交，并且可能会有重大变更。

该项目使用**模型上下文协议 (MCP)**实现了 AI 助手与 FreeCAD CAD 软件之间的强大集成。它允许外部应用程序通过标准化接口与 FreeCAD 交互，并提供多种连接方法和专用工具。

快速启动（推荐：AppImage + Launcher）

为了获得最可靠的设置，请按照以下步骤操作：

  1. 设置环境（一次性） ：运行安装脚本。这会将存储库克隆到~/.mcp-freecad ，创建一个 Python 虚拟环境，下载最新稳定的 FreeCAD AppImage，将其解压，并配置服务器以使用它。
    curl -sSL https://raw.githubusercontent.com/jango-blockchained/mcp-freecad/main/scripts/bin/setup_freecad_env.sh | bash
    或者，克隆 repo 并手动运行./scripts/bin/setup_freecad_env.sh 。
  2. 运行 MCP 服务器：使用安装程序脚本（现在仅确保 venv 处于活动状态并运行服务器）或全局命令（如果已安装）。
    # Option A: Run via the installer script in the default location ~/.mcp-freecad/scripts/bin/mcp-freecad-installer.sh # Option B: Run the global command (if installed via install-global.sh) mcp-freecad

这将使用推荐的launcher方法以及下载并提取的 AppImage 来启动 MCP 服务器。

Docker 支持

您还可以在 Docker 容器中运行 MCP-FreeCAD，以便更轻松地部署和隔离。

使用 Docker Compose 运行

  1. 启动容器：
    docker compose up
  2. 从头开始构建（如果您进行了更改）：
    docker compose build --no-cache docker compose up

Docker 容器公开以下端口：

  • 8080：MCP 服务器
  • 12345：FreeCAD 服务器

Docker 配置

Docker 设置包括：

  • Dockerfile ：使用 Python 3.12 定义容器，安装依赖项并设置环境
  • docker-compose.yml ：配置服务、端口、卷和重启策略
  • .dockerignore ：从容器中排除不必要的文件

此方法对于 CI/CD 管道或需要将 MCP-FreeCAD 环境与系统隔离时特别有用。

🔄 MCP 流程图

此流程图展示了主要组件，以及freecad_connection_manager.py选择的不同连接方法如何导致在 FreeCAD 中执行各种命令。为了确保可靠性，建议使用launcher方法，该方法通常与通过AppRun提取的 AppImage 一起使用。

有关更详细的流程图，请参阅FLOWCHART.md 。

🔄 核心组件

1. FreeCAD MCP 服务器（ freecad_mcp_server.py ）

  • 描述：实现模型上下文协议 (MCP) 的主服务器。它充当 AI 助手或其他客户端通过 MCP 与 FreeCAD 通信的中央枢纽。
  • 特征：
    • 处理标准 MCP 请求（ mcp/listTools 、 mcp/executeTool ）。
    • 利用FreeCADConnection使用配置的方法与 FreeCAD 进行交互。
    • 根据配置公开各种工具集（原语、操作、导出等）。
    • 可通过config.json配置。
  • 用法：
    # Start the server (uses config.json by default) python src/mcp_freecad/server/freecad_mcp_server.py # Start with a specific config python src/mcp_freecad/server/freecad_mcp_server.py --config my_config.json

2. FreeCAD 连接（ freecad_connection_manager.py ）

  • 描述：一个统一的 Python 接口，封装了连接 FreeCAD 的逻辑。由 MCP 服务器内部使用，可直接用于脚本编写。
  • 特征：
    • 根据配置和可用性智能地选择最佳连接方法。
  • 方法：
    • 启动器：（推荐）使用freecad_connection_launcher.py和AppRun 。
    • 包装器：使用freecad_connection_wrapper.py和freecad_subprocess.py 。
    • 服务器：通过套接字连接到正在运行的freecad_socket_server.py 。
    • Bridge ：通过freecad_connection_bridge.py使用 FreeCAD CLI。
    • 模拟：模拟 FreeCAD 进行测试。
    • 自动：按推荐的顺序尝试方法（启动器 > 包装器 > 服务器 > 桥接器 > 模拟）。
  • 用法（直接脚本示例） ：
    from freecad_connection_manager import FreeCADConnection # Auto-connect using settings potentially from config.json # (Ensure config.json is present or provide args) fc = FreeCADConnection(auto_connect=True) if fc.is_connected(): print(f"Connected via: {fc.get_connection_type()}") version_info = fc.get_version() print(f"FreeCAD Version: {version_info}") fc.create_document("TestDocFromScript") else: print("Failed to connect to FreeCAD.")

3. FreeCAD 启动器（ freecad_connection_launcher.py ）

  • 描述：处理 FreeCAD 环境的启动，通常使用从提取的 AppImage 中获取的AppRun 。它在启动的环境中执行freecad_launcher_script.py 。
  • 特征：
    • 管理 FreeCAD/AppRun 的子进程执行。
    • 将命令和参数传递给内部 FreeCAD 脚本。
    • 从脚本的输出中解析 JSON 结果。
  • 用途：主要在选择launcher方法（在config.json中配置）时由FreeCADConnection内部使用。通常不由用户直接运行。

4. FreeCAD 包装器（ freecad_connection_wrapper.py ）和子进程（ freecad_subprocess.py ）

  • 描述： freecad_connection_wrapper.py在单独的 Python 进程中启动freecad_subprocess.py导入 FreeCAD 模块并通过 stdio 管道与包装freecad_subprocess.py通信。
  • 特征：
    • 将 FreeCAD 模块导入隔离到专用进程中。
    • 如果直接模块导入可行但 AppRun/launcher 有问题，则提供替代连接方法。
  • 用法：当选择wrapper方法（在config.json中配置）时，由FreeCADConnection内部使用。需要子进程可以成功import FreeCAD Python 环境。

5. FreeCAD 服务器（ freecad_socket_server.py ）

  • 描述：一个独立的套接字服务器，设计用于在 FreeCAD 实例内运行。监听来自FreeCADConnection的连接。
  • 特征：
    • 允许连接到可能持久的 FreeCAD 实例。
    • 如果在--connect模式下运行，则可以与 GUI 交互。
  • 使用方法（在 FreeCAD 中手动启动） ：
    # Inside FreeCAD Python Console: exec(open("/path/to/mcp-freecad/freecad_socket_server.py").read())
    需要在config.json中配置connection_method: server才能连接 MCP 服务器。 （请参阅docs/FREECAD_SERVER_SETUP.md ）

6.FreeCAD 桥（ freecad_connection_bridge.py ）

  • 描述：启用与 FreeCAD 可执行文件的命令行交互。绕过直接模块导入问题，但速度可能较慢。
  • 特征：
    • 通过对freecad可执行文件的子进程调用来执行 FreeCAD 命令。
  • 用法：当选择bridge方法（在config.json中配置）时，由FreeCADConnection内部使用。要求freecad位于系统 PATH 中或在配置中正确设置的path 。

7. FreeCAD 客户端（ freecad_client.py ）

  • 描述：用于直接与FreeCADConnection接口交互的命令行实用程序（用于测试/调试连接方法，而不是 MCP 服务器）。
  • 特征：
    • 允许从终端测试特定的FreeCADConnection命令（例如，创建原语、获取版本）。
    • 使用config.json来确定连接设置。
  • 使用示例：
    # Test connection and get version python freecad_client.py version # Create a box using the configured connection method python freecad_client.py create-box --length 20 --width 10

🔄 项目结构

MCP-FreeCAD 项目的目录结构如下：

mcp-freecad/ ├── assets/ # 3D model assets (STL, STEP files) ├── backups/ # Backup files ├── config.json # Main configuration file ├── docs/ # Documentation files │ ├── FLOWCHART.md # Detailed flow diagrams │ ├── FREECAD_INTEGRATION.md # FreeCAD integration guide │ ├── FREECAD_SERVER_SETUP.md # Server setup instructions │ ├── OPTIMIZATION_FEATURES.md # Performance optimization guide │ └── PYTHON_INTERPRETER_SETUP.md # Python interpreter configuration ├── examples/ # Example scripts showing API usage ├── freecad_connection_bridge.py # Bridge for CLI interaction with FreeCAD ├── freecad_client.py # Command-line client ├── freecad_connection_manager.py # Unified connection interface ├── freecad_mcp.py # Entry point script ├── freecad_mcp_server.py # MCP server implementation ├── freecad_socket_server.py # Socket-based server for FreeCAD ├── scripts/ # Shell scripts for installation and execution │ ├── README.md # Scripts documentation │ ├── bin/ # Executable scripts │ │ ├── install-global.sh # Global installation script │ │ ├── mcp-freecad-installer.sh # Installer script │ │ ├── mcp-freecad.sh # Simple wrapper script │ │ └── run-freecad-server.sh # Server runner script │ ├── start_freecad_with_server.sh # FreeCAD starter with server │ └── start_server.py # Python script for server startup ├── src/ # Source code ├── tests/ # Test files └── tmp/ # Temporary files

有关脚本的更多详细信息，请参阅scripts/README.md 。

⚙️ 安装和设置详情

本节提供有关不同安装和设置选项的更多详细信息。

推荐设置：AppImage + Launcher（详细步骤）

这涉及两个主要脚本：

  1. scripts/bin/setup_freecad_env.sh ：准备环境。
    • 将存储库克隆或更新至~/.mcp-freecad 。
    • 创建/更新 Python 虚拟环境（ .venv ）并安装要求。
    • 运行download_appimage.py将最新稳定的 FreeCAD Linux AppImage 获取到~/.mcp-freecad中。
    • 运行extract_appimage.py ：
      • 将下载的 AppImage 提取到~/.mcp-freecad/squashfs-root 。
      • 更新~/.mcp-freecad/config.json以使用connection_method: launcher和use_apprun: true以及正确的绝对路径。
    • 如何运行： curl -sSL <URL>/setup_freecad_env.sh | bash或./scripts/bin/setup_freecad_env.sh
  2. scripts/bin/mcp-freecad-installer.sh ：运行服务器。
    • 注意：尽管名称如此，此脚本不再执行完整安装。它主要确保存储库是最新的，激活虚拟环境，并启动freecad_mcp_server.py 。
    • 它假定环境（AppImage 下载/提取）已通过setup_freecad_env.sh或手动准备好。
    • 如何运行： ~/.mcp-freecad/scripts/bin/mcp-freecad-installer.sh或mcp-freecad （全局命令）。

其他安装方法

全局安装（ install-global.sh ）

  • 在/usr/local/bin中创建一个符号链接mcp-freecad指向 repo 中的mcp-freecad-installer.sh 。
  • 允许从任何地方运行mcp-freecad 。
  • 如果您想使用推荐的启动器方法，则需要首先使用setup_freecad_env.sh设置环境。
# Navigate to the repository (e.g., ~/.mcp-freecad) cd ~/.mcp-freecad # Run the setup script first ./scripts/bin/setup_freecad_env.sh # Then run the global installation script sudo ./scripts/bin/install-global.sh # Needs sudo for /usr/local/bin # Now you can run the server from anywhere mcp-freecad

手动安装

  • 克隆 repo。
  • 创建 venv，安装要求。
  • 手动下载并提取 AppImage ：自行运行python download_appimage.py和python extract_appimage.py /path/to/downloaded.AppImage 。
  • 运行服务器： python freecad_mcp_server.py 。

🚀 使用 MCP 服务器

这是使用 Claude 等 AI 助手与 FreeCAD 交互的主要方式。

启动 MCP 服务器

# Start the server using the default config.json python src/mcp_freecad/server/freecad_mcp_server.py # Start with a specific configuration file python src/mcp_freecad/server/freecad_mcp_server.py --config /path/to/your/config.json # Enable debug logging python src/mcp_freecad/server/freecad_mcp_server.py --debug

服务器将运行并监听来自 MCP 客户端的连接。

连接 MCP 客户端

使用任何兼容 MCP 的客户端。以下是使用参考mcp client示例：

# Replace 'mcp client' with the actual client command if different mcp client connect stdio --command "python src/mcp_freecad/server/freecad_mcp_server.py"

或者如果您有一个客户端脚本（如 MCP 文档中的脚本），则使用uv ：

uv run path/to/your/mcp_client.py python src/mcp_freecad/server/freecad_mcp_server.py

替代方案：使用集成服务器启动 FreeCAD

您还可以使用集成服务器启动 FreeCAD：

./scripts/start_freecad_with_server.sh

这将启动 FreeCAD 并自动启动其中的服务器。

MCP 服务器配置（ config.json ）

config.json文件控制服务器的各个方面。以下示例反映了运行extract_appimage.py后推荐的启动器设置：

{ "auth": { // Optional authentication settings "api_key": "development", "enabled": false }, "server": { // MCP server settings "host": "0.0.0.0", "port": 8000, "debug": true, "workers": 1, "name": "mcp-freecad", "version": "0.3.1", // Example version "mcp": { "transport": "stdio", // Use stdio for Cursor/local clients "protocol_version": "0.1.0" // ... other MCP settings } }, "freecad": { // FreeCAD connection settings // Paths are set automatically by extract_appimage.py for launcher mode "path": "/home/user/mcp-freecad/squashfs-root/usr/bin/freecad", // Example path "python_path": "/home/user/mcp-freecad/squashfs-root/usr/bin/python", // Example path "module_path": "/home/user/mcp-freecad/squashfs-root/usr/lib/", // Example path "host": "localhost", // Not used by launcher "port": 12345, // Not used by launcher "auto_connect": false, // Connection handled internally "reconnect_on_failure": true, "use_mock": false, "connection_method": "launcher", // *** KEY: Use the launcher method *** "script_path": "/home/user/mcp-freecad/freecad_launcher_script.py", // Script run inside FreeCAD "launcher_path": "/home/user/mcp-freecad/freecad_connection_launcher.py", // Script that starts AppRun "use_apprun": true, // *** KEY: Tells launcher to use AppRun *** "apprun_path": "/home/user/mcp-freecad/squashfs-root/AppRun" // Path to AppRun executable }, "logging": { // Logging configuration "level": "INFO", "file": "mcp_freecad.log", "max_size": 10485760, "backup_count": 3 }, "tools": { // Optional: control which tool groups are enabled "enable_smithery": true, "enable_primitives": true, "enable_model_manipulation": true, "enable_export_import": true, "enable_measurement": true, "enable_code_generator": true // ... other tool settings } // ... other sections like cache, recovery, cors, performance ... }

注意：用实际的绝对路径替换示例路径。

有关集成选项的更多详细信息，请参阅FREECAD_INTEGRATION.md 。

🛠️ 可用的 MCP 工具

MCP 服务器提供了各种工具组。以下是所有可用的工具：

📐 基本 FreeCAD 工具（ freecad.* ）

  • freecad.create_document ：创建一个新文档
  • freecad.export_stl ：将模型或特定对象导出为 STL
  • freecad.import_stl ：将 STL 文件导入当前文档
  • freecad.save_document ：保存当前文档
  • freecad.load_document ：加载现有文档

🔧 模型操作工具（ model_manipulation.* ）

  • model_manipulation.rotate ：围绕指定轴旋转物体
  • model_manipulation.translate ：在 3D 空间中移动物体
  • model_manipulation.scale ：均匀或非均匀缩放对象
  • model_manipulation.mirror ：跨指定平面镜像对象
  • model_manipulation.union ：使用布尔联合组合多个对象
  • model_manipulation.cut ：使用布尔差异剪切对象
  • model_manipulation.intersect ：创建多个对象的交集

📏 测量工具（ measurement.* ）

  • measurement.distance ：测量两点之间的距离
  • measurement.angle ：测量三点之间的角度
  • measurement.area ：计算物体的表面积
  • measurement.volume ：计算固体物体的体积
  • measurement.mass ：计算物体的质量（需要材料特性）

📦 基元工具（ primitives.* ）

  • primitives.create_box ：创建一个矩形框
  • primitives.create_cylinder ：创建圆柱体
  • primitives.create_sphere ：创建一个球体
  • primitives.create_cone ：创建一个圆锥体
  • primitives.create_torus ：创建圆环
  • primitives.create_polygon ：创建一个正多边形
  • primitives.create_ellipse ：创建椭圆

🔄 导出/导入工具（ export_import.* ）

  • export_import.export_step ：导出为 STEP 格式
  • export_import.import_step ：从 STEP 格式导入
  • export_import.export_iges ：导出为 IGES 格式
  • export_import.import_iges ：从 IGES 格式导入
  • export_import.export_dxf ：导出为 DXF 格式
  • export_import.import_dxf ：从 DXF 格式导入

💻 代码生成工具（ code_generator.* ）

  • code_generator.generate_python ：为当前模型生成 Python 代码
  • code_generator.generate_openscad ：为当前模型生成 OpenSCAD 代码
  • code_generator.generate_gcode ：生成用于 CNC 加工的 G 代码
  • code_generator.generate_3d_print ：生成优化的 3D 打印设置

📝 MCP 交互示例

以下是将 MCP 服务器与 AI 助手结合使用的概念示例：

创建并导出盒子

User: Create a box 50mm long, 30mm wide, and 20mm high. Assistant: Okay, I can create that box. [Tool Call: primitives.create_box (arguments: {"length": 50.0, "width": 30.0, "height": 20.0})] [Tool Result: {"object_name": "Box", "message": "Created box...", "success": true}] User: Now export it as box.stl Assistant: Sure, exporting the model to box.stl. [Tool Call: export_import.export_stl (arguments: {"file_path": "box.stl", "object_names": ["Box"]})] [Tool Result: {"file_path": "box.stl", "message": "Exported successfully...", "success": true}] Assistant: I've exported the box model to `box.stl`.

🔍 故障排除

  • MCP 服务器连接问题：
    • 确保python src/mcp_freecad/server/freecad_mcp_server.py可以正常运行，不会立即出现错误。检查终端输出。
    • 检查防火墙设置是否相关（对于stdio来说不太可能）。
    • 验证config.json是否为有效的 JSON。
  • FreeCAD 连接问题（尤其是launcher方法） ：
    • 运行extract_appimage.py ：确保正确提取了 AppImage 并且更新了config.json 。
    • 检查config.json路径：验证freecad部分中的所有绝对路径是否适合您的系统。
    • 检查权限：确保squashfs-root/AppRun具有执行权限（ chmod +x ）。
    • 检查日志：检查mcp_freecad.log （如果开始日志记录，则在项目根目录中创建）、 freecad_server_stdout.log和freecad_server_stderr.log是否存在来自freecad_connection_launcher.py 、 AppRun或 FreeCAD 进程本身的错误。
    • 环境变量：如果AppRun无法找到库，请确保正确设置LD_LIBRARY_PATH和PYTHONPATH 。如果使用 Cursor，则可能在.cursor/mcp.json中设置；如果在终端中测试，则需要extract_appimage.py导出。extract_appimage.py 脚本旨在减少这方面的必要性，但它也可能是一个影响因素。
    • 无头问题：FreeCAD 有时会在完全无头运行时出现问题（ QT_QPA_PLATFORM=offscreen ）。请检查日志中是否存在与 GUI 相关的错误。
  • server方法：确保freecad_socket_server.py在活动的 FreeCAD 实例中运行，并监听config.json中配置的正确主机/端口。
  • bridge方法：验证 FreeCAD 是否已在系统范围内安装，以及freecad命令是否在终端中正常运行。检查config.json中的freecad_path 。
  • 缺少 MCP SDK ：通过pip install modelcontextprotocol安装。
  • Python 路径问题：如果在不使用推荐的 AppImage 设置时找不到 FreeCAD 模块，请参阅PYTHON_INTERPRETER_SETUP.md 。

📄 许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

🖥️ 光标集成

MCP 服务器设计用于与 Cursor IDE 等工具集成。

  1. 配置 Cursor ：在 Cursor 的设置中添加 MCP 服务器（设置 > 功能 > MCP 服务器 > 添加新 MCP 服务器）。将其配置为直接运行 Python 脚本，并设置必要的环境变量和工作目录。.cursor .cursor/mcp.json中的示例配置如下：
    { "mcpServers": { "mcp-freecad": { "command": "python3", // Command to run python "args": [ "src/mcp_freecad/server/freecad_mcp_server.py" // Script to run ], "env": { // Environment variables needed for headless AppRun "QT_QPA_PLATFORM": "offscreen", "DISPLAY": "", "FREECAD_CONSOLE": "1", "PYTHONNOUSERSITE": "1", // These might be needed if AppRun doesn't set them automatically "LD_LIBRARY_PATH": "/path/to/mcp-freecad/squashfs-root/usr/lib:/path/to/mcp-freecad/squashfs-root/usr/Ext:...", "PYTHONPATH": "/path/to/mcp-freecad/squashfs-root/usr/lib/python3.11/site-packages:..." }, "cwd": "/path/to/mcp-freecad" // Set working directory to project root } // ... other servers like memory ... } }
    将/path/to/mcp-freecad替换为项目的实际绝对路径。 如有需要，请确保LD_LIBRARY_PATH和PYTHONPATH与您的 AppImage 结构匹配。
  2. 重新启动 Cursor ：完全重新启动 Cursor 以使配置更改生效。
  3. 服务器通信：服务器默认使用stdio传输（在config.json的server.mcp.transport下配置），该协议与 Cursor 的通信协议兼容。错误应通过 MCP 错误响应报告给 Cursor。

游标特定注意事项

  • freecad_mcp_server.py脚本默认加载config.json 。请确保此文件包含正确的设置，尤其是由extract_appimage.py更新的freecad部分。
  • .cursor/mcp.json中设置的环境变量对于launcher方法在 Cursor 提供的环境中正常工作至关重要。

📋 可用选项和用例

🔧 连接方法

  1. 启动器连接（推荐）
    • 使用从提取的 AppImage 中获取的AppRun 。非常可靠。
    • 由extract_appimage.py自动配置。
    • 配置（ config.json ）：GXP19
  2. 包装器连接
    • 在单独的 Python 子进程中运行 FreeCAD 逻辑。如果 AppImage/AppRun 出现问题，这是一个不错的替代方案。
    • 配置（ config.json ）：GXP20
  3. 套接字服务器连接
    • 需要在 FreeCAD 中运行freecad_socket_server.py 。
    • 当运行 FreeCAD 作为持久后台服务器时使用。
    • 配置（ config.json ）：GXP21
  4. CLI 桥接连接
    • 使用freecad命令行工具。速度可能较慢/可靠性较低。
    • 配置（ config.json ）：GXP22
  5. 模拟连接
    • 无需 FreeCAD 即可进行测试。
    • 配置（ config.json ）：GXP23
  6. 自动连接
    • 自动选择最佳可用方法（启动器 > 包装器 > 服务器 > 桥接器 > 模拟）。
    • 如果connection_method缺失或设置为"auto"则为默认值。

🛠️ 工具类别和用例

  1. 基本 FreeCAD 操作
    • 基本文件管理
    • 使用案例：
      • 创建新文档
      • 保存和加载项目
      • 导出为各种格式
      • 管理文档结构
  2. 模型操作
    • 变换和修改对象
    • 使用案例：
      • 精确旋转物体
      • 在 3D 空间中移动物体
      • 缩放模型
      • 创建镜像和副本
      • 布尔运算（并集、切集、交集）
  3. 测量工具
    • 分析与验证
    • 使用案例：
      • 距离测量
      • 角度计算
      • 表面积分析
      • 体积计算
      • 质量特性
  4. 原始创造
    • 基本形状生成
    • 使用案例：
      • 创建盒子和圆柱体
      • 生成球体
      • 制作圆锥体和圆环体
      • 创建正多边形
      • 绘制椭圆
  5. 出口/进口操作
    • 文件格式转换
    • 使用案例：
      • STEP 文件导出/导入
      • IGES 格式处理
      • DXF文件处理
      • STL 导出用于 3D 打印
  6. 代码生成
    • 自动代码创建
    • 用例：
      • Python 脚本生成
      • OpenSCAD 代码导出
      • CNC 的 G 代码生成
      • 3D打印机设置优化

💻 集成场景

  1. Cursor IDE 集成
    • 开发环境集成
    • 使用案例：
      • 从 IDE 直接操作模型
      • 实时反馈
      • 调试日志记录
      • 错误追踪
  2. AI助手集成
    • 人工智能设计自动化
    • 使用案例：
      • 自然语言模型创建
      • 自动化设计修改
      • 参数优化
      • 设计验证
  3. 命令行用法
    • 脚本和自动化
    • 使用案例：
      • 批处理
      • 自动化测试
      • CI/CD 集成
      • 命令行工具

🎯 常见用例示例

  1. 快速成型
# Create a new document freecad.create_document("Prototype") # Add basic shapes primitives.create_box(length=100, width=50, height=20) # Export for 3D printing export_import.export_stl("prototype.stl")
  1. 自动化处理
# Import and modify multiple files for file in files: import_step(file) model_manipulation.scale(1.5) export_stl(f"{file}_scaled.stl")

⚙️ 配置选项

  1. 服务器配置
{ "server": { "name": "custom-server-name", "version": "1.0.0", "description": "Custom description" } }
  1. 工具启用
{ "tools": { "enable_smithery": true, "enable_primitives": true, "enable_model_manipulation": true, "enable_export_import": true, "enable_measurement": true, "enable_code_generator": true } }
  1. 调试配置
{ "cursor": { "debug": true, "log_level": "DEBUG", "stdio_transport": true } }

特征

  • 通过 MCP 协议将 AI 助手连接到 FreeCAD
  • 以编程方式创建和操作 3D 模型
  • 支持原始形状（盒子、圆柱体、球体、圆锥体）
  • 布尔运算（并集、交集、切集）
  • 对象变换（移动、旋转）
  • 将模型导出为 STL 格式
  • 文档和对象管理

先决条件

  • Python 3.8 或更高版本
  • MCP SDK（ pip install modelcontextprotocol ）
  • 推荐：FreeCAD AppImage（使用extract_appimage.py下载并提取）用于可靠的launcher连接方法。
  • 或者：FreeCAD 0.20+ 的系统安装（用于bridge或server方法，可能不太可靠）。

可用工具

文档管理

  1. freecad.create_document - 创建一个新的 FreeCAD 文档
  2. freecad.list_documents - 列出所有打开的文档
  3. freecad.list_objects - 列出文档中的所有对象

3D基元

  1. freecad.create_box - 创建一个盒子原语
  2. freecad.create_cylinder - 创建圆柱体图元
  3. freecad.create_sphere - 创建一个球体图元
  4. freecad.create_cone - 创建一个圆锥体图元

布尔运算

  1. freecad.boolean_union - 创建两个对象的并集（添加）
  2. freecad.boolean_cut - 从第一个对象中剪切第二个对象（减去）
  3. freecad.boolean_intersection - 创建两个对象的交集（公共体积）

变换

  1. freecad.move_object - 将对象移动到新位置
  2. freecad.rotate_object - 旋转对象

出口

  1. freecad.export_stl - 将模型导出为 STL 文件

测试

该项目包括单元测试和端到端（E2E）测试，以确保质量和可靠性。

单元测试

运行基本单元测试：

python test_mcp_tools.py python test_mcp_client.py

端到端测试

端到端测试从客户端的角度验证整个系统是否正常运行。它们测试真实场景以及不同组件之间的交互。

要运行所有 E2E 测试：

# Run with mock FreeCAD (default, doesn't require actual FreeCAD installation) ./tests/e2e/run_tests.py # Run with verbose output ./tests/e2e/run_tests.py --verbose # Run with real FreeCAD connection (requires FreeCAD to be installed) ./tests/e2e/run_tests.py --real # Run a specific test file ./tests/e2e/run_tests.py --single test_primitives.py

E2E 测试按功能组织：

  • test_primitives.py - 测试基本形状的创建和操作
  • test_smithery.py - 锻造工具操作测试

编写新的 E2E 测试

要添加新的 E2E 测试：

  1. 在tests/e2e/目录中创建一个新的测试文件
  2. 扩展适当的基测试类（ MCPClientTestBase ）
  3. 添加使用 MCP 客户端与工具交互的测试方法
  4. 使用测试运行器运行测试

请参阅现有的测试文件以获取示例。

文档

该项目包括针对不同方面的几个文档文件：

对于AI助手，请参阅AI_ASSISTANT_GUIDE.md以获取详细的使用说明和示例。

贡献

欢迎贡献代码！欢迎提交 Pull 请求。

致谢

  • FreeCAD 开发团队打造了出色的 CAD 软件
  • Anthropic 和 Claude 用于模型上下文协议 (MCP) SDK

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

该项目使用模型上下文协议 (MCP)，实现了 AI 助手与 FreeCAD CAD 软件之间的强大集成。它允许外部应用程序通过标准化接口与 FreeCAD 交互，并提供多种连接方法和专用工具。

  1. Quick Start (Recommended: AppImage + Launcher)
    1. Docker Support
      1. Running with Docker Compose
      2. Docker Configuration
    2. 🔄 MCP Flow Chart
      1. 🔄 Core Components
        1. 1. FreeCAD MCP Server (freecad_mcp_server.py)
        2. 2. FreeCAD Connection (freecad_connection_manager.py)
        3. 3. FreeCAD Launcher (freecad_connection_launcher.py)
        4. 4. FreeCAD Wrapper (freecad_connection_wrapper.py) & Subprocess (freecad_subprocess.py)
        5. 5. FreeCAD Server (freecad_socket_server.py)
        6. 6. FreeCAD Bridge (freecad_connection_bridge.py)
        7. 7. FreeCAD Client (freecad_client.py)
      2. 🔄 Project Structure
        1. ⚙️ Installation & Setup Details
          1. Recommended Setup: AppImage + Launcher (Detailed Steps)
          2. Other Installation Methods
        2. 🚀 Using the MCP Server
          1. Starting the MCP Server
          2. Connecting an MCP Client
          3. Alternative: Starting FreeCAD with Integrated Server
          4. MCP Server Configuration (config.json)
        3. 🛠️ Available MCP Tools
          1. 📐 Basic FreeCAD Tools (freecad.*)
          2. 🔧 Model Manipulation Tools (model_manipulation.*)
          3. 📏 Measurement Tools (measurement.*)
          4. 📦 Primitives Tools (primitives.*)
          5. 🔄 Export/Import Tools (export_import.*)
          6. 💻 Code Generation Tools (code_generator.*)
        4. 📝 Example MCP Interactions
          1. Creating and Exporting a Box
        5. 🔍 Troubleshooting
          1. 📄 License
            1. 🖥️ Cursor Integration
              1. Cursor-Specific Considerations
            2. 📋 Available Options and Use Cases
              1. 🔧 Connection Methods
              2. 🛠️ Tool Categories and Use Cases
              3. 💻 Integration Scenarios
              4. 🎯 Common Use Case Examples
              5. ⚙️ Configuration Options
            3. Features
              1. Prerequisites
                1. Available Tools
                  1. Document Management
                  2. 3D Primitives
                  3. Boolean Operations
                  4. Transformations
                  5. Export
                2. Testing
                  1. Unit Tests
                  2. End-to-End Tests
                3. Documentation
                  1. Contributing
                    1. Acknowledgments
                      ID: hee3my85fb