Skip to main content
Glama
enesjakozh
jango-blockchained

mcp-freecad

by jango-blockchained
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

🛠️ MCP-FreeCAD 集成

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

许可证：MIT Python 版本 代码样式：flake8 项目状态：活跃

该项目使用**模型上下文协议 (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 并手动运行

  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 服务器。

Related MCP server: FreeCAD 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 流程图

graph TD subgraph "Client" A["AI Assistant / MCP Client"] end subgraph "Server & Connection" B["MCP Server (freecad_mcp_server.py)"] C["FreeCAD Connection (freecad_connection_manager.py)"] C_Auto{"Auto-Select Method"} end subgraph "Connection Methods (Backends)" D["Server Mode (freecad_socket_server.py)"] E["Bridge Mode (freecad_connection_bridge.py)"] F["Wrapper Mode (freecad_connection_wrapper.py)"] L["Launcher Mode (freecad_connection_launcher.py)"] M["Mock Mode"] end subgraph "FreeCAD Execution" FS["Socket Server inside FreeCAD"] FCLI["FreeCAD CLI"] FSub["FreeCAD via Subprocess"] FAppRun["FreeCAD via AppRun"] G["FreeCAD Instance/Modules"] end %% Client to Server A --> |MCP Request| B %% Server uses Connection Layer B --> |Requests Connection| C %% Connection Logic C --> C_Auto C_Auto -- "Pref=Launcher or Auto" --> L C_Auto -- "Pref=Wrapper or Auto Fail" --> F C_Auto -- "Pref=Server or Auto Fail" --> D C_Auto -- "Pref=Bridge or Auto Fail" --> E C_Auto -- "Pref=Mock or Auto Fail" --> M %% Backends to Execution L --> |"Uses AppRun"| FAppRun F --> |"Uses freecad_subprocess.py"| FSub D --> |"Connects via Socket"| FS E --> |"Calls CLI"| FCLI %% Execution to FreeCAD FAppRun --> G FSub --> G FS --> G FCLI --> G %% Style (Optional) classDef client fill:#cde4ff,stroke:#333,stroke-width:1px; classDef server fill:#ccffcc,stroke:#333,stroke-width:1px; classDef backend fill:#fff0cc,stroke:#333,stroke-width:1px; classDef execution fill:#ffcccc,stroke:#333,stroke-width:1px; class A,B,C,C_Auto client; class D,E,F,L,M backend; class FS,FCLI,FSub,FAppRun,G execution;

此流程图展示了主要组件，以及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 连接（ src/mcp_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())

    需要在 （请参阅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 ├── config.template.json # Template for configuration ├── 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/Runner script │ ├── mcp-freecad # Link target for global install │ └── setup_freecad_env.sh # Environment setup script (AppImage download/extract) ├── src/ # Source code (contains mcp_freecad package) │ └── mcp_freecad/ │ ├── __init__.py │ ├── server/ │ │ ├── __init__.py │ │ └── freecad_mcp_server.py # The main MCP server implementation │ ├── freecad_connection_manager.py # Unified connection interface │ └── ... # Other source files ├── tests/ # Test files │ └── e2e/ # End-to-end tests ├── .gitignore # Git ignore patterns ├── pyproject.toml # Project metadata and dependencies (PEP 621) ├── LICENSE # Project License ├── README.md # This file ├── Dockerfile # Docker build definition ├── docker-compose.yml # Docker Compose configuration └── ... # Other config files (.dockerignore, .editorconfig, etc.)

有关脚本的更多详细信息，请参阅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.7.11", "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.create_document ：创建一个新文档。

  • freecad.list_documents ：列出所有打开的文档。

  • freecad.list_objects ：列出特定文档（或活动文档）中的对象。

  • freecad.create_box ：创建一个盒子图元。

  • freecad.create_cylinder ：创建一个圆柱体图元。

  • freecad.create_sphere ：创建一个球体图元。

  • freecad.create_cone ：创建一个圆锥体图元。

  • freecad.boolean_union ：在两个对象之间执行布尔联合（融合）。

  • freecad.boolean_cut ：在两个对象之间执行布尔切割（差异）。

  • freecad.boolean_intersection ：在两个对象之间执行布尔交集（常见）。

  • freecad.move_object ：将对象移动到新的绝对位置。

  • freecad.rotate_object ：按指定角度旋转对象。

  • freecad.export_stl ：将指定对象（或全部）导出到 STL 文件。

（注意：MCP 请求中使用的工具名称可能略有不同，例如，使用下划线而不是点，具体取决于客户端和服务器的实现细节。请参阅服务器的mcp/listTools输出以获取确切名称。）

📝 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 连接问题（尤其是 ：

    • 运行 ：确保正确提取了 AppImage 并且更新了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" // Corrected script path ], "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 ... } }

    将 如有需要，请确保

  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 或更高版本

  • 推荐：FreeCAD AppImage（使用scripts/bin/setup_freecad_env.sh下载并提取）用于可靠的launcher连接方法。

  • 或者：FreeCAD 0.20+ 的系统安装（用于bridge或server方法，可能不太可靠）。

  • Git（用于克隆存储库）。

依赖项通过pyproject.toml进行管理，并在设置期间安装到虚拟环境中。

可用工具

（本节重复上面的列表 - 为了清晰起见进行合并）

目前可通过 MCP 实现的工具有：

文档管理

  • freecad.create_document

  • freecad.list_documents

  • freecad.list_objects

3D基元

  • freecad.create_box

  • freecad.create_cylinder

  • freecad.create_sphere

  • freecad.create_cone

布尔运算

  • freecad.boolean_union

  • freecad.boolean_cut

  • freecad.boolean_intersection

变换

  • freecad.move_object

  • freecad.rotate_object

出口

  • freecad.export_stl

我们计划在未来的版本中推出涵盖测量、其他导入/导出格式和代码生成的附加工具。

测试

该项目包括端到端（E2E）测试以验证系统功能。

端到端测试

这些测试使用 MCP 协议从客户端的角度验证交互。

要运行所有 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 and configured) ./tests/e2e/run_tests.py --real # Run a specific test file (e.g., test_primitives.py) ./tests/e2e/run_tests.py --single test_primitives.py

E2E 测试位于tests/e2e/目录中，并按功能组织。

编写新的 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

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jango-blockchained/mcp-freecad'

If you have feedback or need assistance with the MCP directory API, please join our Discord server