Skip to main content
Glama
Sign In
enesjakozh

mcp-freecad

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

🛠️ 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 连接（ 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())
    需要在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 ├── 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 连接问题（尤其是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" // 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 ... } }
    将/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 或更高版本
  • 推荐：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

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

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

  1. 快速启动（推荐：AppImage + Launcher）
    1. Docker 支持
      1. 使用 Docker Compose 运行
      2. Docker 配置
    2. 🔄 MCP 流程图
      1. 🔄 核心组件
        1. FreeCAD MCP 服务器（ freecad_mcp_server.py ）
        2. FreeCAD 连接（ src/mcp_freecad/freecad_connection_manager.py ）
        3. FreeCAD 启动器（ freecad_connection_launcher.py ）
        4. FreeCAD 包装器（ freecad_connection_wrapper.py ）和子进程（ freecad_subprocess.py ）
        5. FreeCAD 服务器（ freecad_socket_server.py ）
        6. 6.FreeCAD 桥（ freecad_connection_bridge.py ）
        7. FreeCAD 客户端（ freecad_client.py ）
      2. 🔄 项目结构
        1. ⚙️ 安装和设置详情
          1. 推荐设置：AppImage + Launcher（详细步骤）
          2. 其他安装方法
        2. 🚀 使用 MCP 服务器
          1. 启动 MCP 服务器
          2. 连接 MCP 客户端
          3. 替代方案：使用集成服务器启动 FreeCAD
          4. MCP 服务器配置（ config.json ）
        3. 🛠️ 可用的 MCP 工具
          1. 📝 MCP 交互示例
            1. 创建并导出盒子
          2. 🔍 故障排除
            1. 📄 许可证
              1. 🖥️ 光标集成
                1. 游标特定注意事项
              2. 📋 可用选项和用例
                1. 🔧 连接方法
                2. 🛠️ 工具类别和用例
                3. 💻 集成场景
                4. 🎯 常见用例示例
                5. ⚙️ 配置选项
              3. 特征
                1. 先决条件
                  1. 可用工具
                    1. 文档管理
                    2. 3D基元
                    3. 布尔运算
                    4. 变换
                    5. 出口
                  2. 测试
                    1. 端到端测试
                  3. 文档
                    1. 贡献
                      1. 致谢

                        Related MCP Servers

                        • OpenAI MCP Server

                          thadius83
                          A
                          security
                          A
                          license
                          A
                          quality
                          Enables integration with OpenAI models through the MCP protocol, supporting concise and detailed responses for use with Claude Desktop.
                          Last updated -
                          1
                          1
                          Python
                          MIT License
                          • Apple
                          • Linux

                        • BlenderMCP

                          ahujasid
                          -
                          security
                          A
                          license
                          -
                          quality
                          Connects Blender to Claude AI through the Model Context Protocol (MCP), allowing Claude to directly interact with and control Blender for AI-assisted 3D modeling, scene manipulation, and rendering.
                          Last updated -
                          10,093
                          Python
                          MIT License
                          • Apple

                        • FreeCAD MCP

                          bonninr
                          -
                          security
                          A
                          license
                          -
                          quality
                          A FreeCAD addon that implements the Model Context Protocol (MCP) to enable communication between FreeCAD and Claude AI through Claude Desktop.
                          Last updated -
                          17
                          Python
                          MIT License
                          • Linux
                          • Apple

                        • Revit MCP

                          revit-mcp
                          A
                          security
                          A
                          license
                          A
                          quality
                          Allows AI to interact with Autodesk Revit via the MCP protocol, enabling retrieval of project data and automation of tasks like creating, modifying, and deleting elements.
                          Last updated -
                          11
                          109
                          TypeScript
                          MIT License

                        View all related MCP servers

                        New MCP Servers

                        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