MCP Freecad

🛠️ MCP FreeCAD集成

状态： 主动开发-干净、有组织的代码库，具有多种连接方法和全面的工具提供商。

 ](https://www.python.org/)  

该项目使用 模型上下文协议（MCP）。它允许外部应用程序通过标准化接口与FreeCAD交互，提供多种连接方法和专用工具。

______________________________________________________________________

🤖 人工智能提供商模型（2025）

MCP FreeCAD集成支持多个具有最新2025型号的AI提供商。为您的特定用例选择合适的型号：

OpenAI模型

生产型号：

• gpt-4o -默认多模式模型（文本、图像、音频）

- 上下文：128K令牌 - 定价：每100万输入代币约5美元 - 最适合：通用CAD任务、多模式交互

• gpt-4.1 -具有1M令牌上下文的下一代

- 功能：文本、图像、音频、视频支持 - 定价：每100万输入代币约2.5美元 - 最适合：复杂的CAD项目、大型文档分析

• gpt-4涡轮增压器 -快速、经济高效

- 上下文：128K令牌 - 最适合：大批量操作、批量处理

推理模型：

• 臭氧 -复杂CAD逻辑的高级推理

- 定价：每100万输入代币约10美元 - 最适合：复杂几何计算、设计优化

• o4迷你 / o4迷你高 -成本效益推理

- 定价：每100万输入代币约0.15美元 - 最适合：简单计算，快速迭代

拟人克劳德模型

克劳德4系列（2025）：

• claude-opus-4 -最先进的型号

- 最大上下文：20万个令牌 - 定价：每百万代币15美元/75美元（输入/输出） - 特点：扩展思维、工具使用、记忆处理 - 最适合：复杂的CAD工作流程、自主设计任务

• claude-sonnet-4 -平衡效率

- 最大上下文：20万个令牌 - 定价：每百万代币3美元/15美元 - 特点：高级编码，混合推理 - 最适合：一般CAD操作、脚本辅助

• claude-haiku-3.5 -快速、轻便

- 最适合：快速查询，简单操作

谷歌人工智能模型

Gemini 2.5系列（最新）：

• 双子座-2.5-pro-review-05-06 -最先进

- 上下文：1M代币 - 特点：增强推理、思维方式 - 最适合：复杂的CAD分析、大型装配

• 双子座-2.5激光预览-04-17 -性能优化

- 特点：适应性思维，性价比高 - 最适合：平衡性能和成本

Gemini 2.0系列（稳定型）：

• 双子座-2.0-flash-001 -生产就绪

- 特点：比Gemini 1.5 Pro快2倍 - 最适合：实时CAD辅助

• 双子座-2.0-flash-lite -成本优化

- 最适合：体积大，操作简单

OpenRouter（统一接入）

OpenRouter通过单个API提供对所有模型的访问：

模型格式： provider/model-name

热门型号：

• anthropic/claude-sonnet-4 -推荐的一般用途
• openai/gpt-4o -OpenAI的旗舰
• google/gemini-2.5-pro-preview -谷歌最新

免费型号（50-1000个请求/天）：

• deepseek/deepseek-r1 -高级推理
• deepseek/deepseek-v3 -一般用途
• google/gemini-2.5-flash-preview -谷歌免费版

选型指南

配置示例

{
  "providers": {
    "anthropic": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "thinking_mode": true,
      "max_tokens": 64000
    },
    "openai": {
      "enabled": true,
      "model": "gpt-4o",
      "max_tokens": 32000
    },
    "google": {
      "enabled": true,
      "model": "gemini-2.0-flash-001",
      "thinking_mode": true
    },
    "openrouter": {
      "enabled": true,
      "model": "anthropic/claude-sonnet-4",
      "free_models": ["deepseek/deepseek-r1"]
    }
  }
}

API使用示例

# Using specific provider
from freecad_ai import CADAssistant

# Initialize with Claude Sonnet 4
assistant = CADAssistant(provider="anthropic", model="claude-sonnet-4")

# Create complex geometry
result = assistant.generate_cad_script(
    "Create a parametric gear with 20 teeth, 5mm module, and 20° pressure angle"
)

# Using OpenRouter for cost optimization
assistant_free = CADAssistant(
    provider="openrouter", 
    model="deepseek/deepseek-r1"
)

# Quick operations with free model
result = assistant_free.create_primitive("box", length=10, width=5, height=3)

______________________________________________________________________

🚀 快速开始

选项1:FreeCAD插件（推荐给用户）

为了获得GUI集成的最佳用户体验：

📦 FreeCAD MCP集成插件

• 🧠 克劳德4与思维方式 -高级AI推理
• 🤖 多提供商支持 -Claude、Gemini、OpenRouter，拥有13款以上型号
• 🎨 现代图形用户界面 -专业标签式界面
• 🔗 通用连接 -所有MCP连接方法
• 📊 性能监控 -实时诊断

选项2:MCP服务器（适用于开发人员/集成）

# Clone the repository
git clone https://github.com/jango-blockchained/mcp-freecad.git
cd mcp-freecad

# Install dependencies
pip install -r requirements.txt

# Start the MCP server
python mcp_server.py

# Or with FastMCP mode (lightweight, ideal for Cursor IDE)
python mcp_server.py --mode fastmcp

# Or with custom config and debug logging
python mcp_server.py --config my_config.json --debug

python-m src.mcp_freecad.main--配置my_config json--调试

### Option 3: FastMCP Server (Cursor IDE & Latest Best Practices)

**✨ NEW: Updated to FastMCP 2.13.0.2** - Modern, declarative MCP server implementation.

Start the FastMCP server for Cursor IDE

python cursor_mcp_server.py

Or run the example to see available tools

python example_fastmcp_usage.py --all

**主要特点：**

- 🎯 **声明性API** -简单 `@mcp.tool()` 和 `@mcp.resource()` 装饰器
- 🔒 **类型安全** -从类型提示自动生成架构
- 🚀 **最佳实践** -遵循FastMCP 2.13推荐的模式
- ✅ **测试良好** -综合测试套件，合格率100%
- 📚 **优秀的文档** -请参阅 [FASTCMP_实施.md](docs/FASTMCP_IMPLEMENTATION.md)

**可用工具：**

- `test_connection` -测试FreeCAD连接
- `create_box` -创建长方体图元
- `create_cylinder` -创建圆柱体
- `create_sphere` -创建球体
- `create_document` -管理FreeCAD文档

**资源：**

- `freecad://status` -获取服务器状态和FreeCAD可用性

有关详细用法，请参阅 [FastMCP实施指南](docs/FASTMCP_IMPLEMENTATION.md).

______________________________________________________________________

## 🏗️ **架构概述**

### 核心组件

src/mcp_freecad/ ├── main.py # Main entry point ├── __init__.py # Package exports and registry ├── client/ # FreeCAD connection management │ └── freecad_connection_manager.py ├── server/ # MCP server implementation │ └── freecad_mcp_server.py ├── tools/ # Tool providers │ ├── base.py # Base tool provider class │ ├── primitives.py # Primitive shapes (box, cylinder, etc.) │ ├── model_manipulation.py # Transform, boolean ops, etc. │ ├── export_import.py # File format handling │ ├── measurement.py # Analysis tools │ └── code_generator.py # Code generation ├── core/ # Core infrastructure │ ├── server.py # FastAPI-based server │ ├── cache.py # Resource caching │ ├── diagnostics.py # Performance monitoring │ └── recovery.py # Connection recovery └── connections/ # Connection backends

### 连接方法

系统支持多种方式连接到FreeCAD：

1. **🚀 启动器** （推荐）-将AppImage与AppRun结合使用
1. **🔌 服务器** -基于套接字的FreeCAD服务器连接
1. **🌉 桥** -使用FreeCAD可执行文件进行基于CLI的连接
1. **📡 远程过程调用** -与FreeCAD的XML-RPC连接
1. **📦 包装器** -子进程包装器连接
1. **🎭 模拟** -用于无FreeCAD的测试

______________________________________________________________________

## 🛠️ **可用工具**

### 原始创造

- `create_box` -创建长方体图元
- `create_cylinder` -创建圆柱体
- `create_sphere` -创建球体
- `create_cone` -创建圆锥体

### 模型操纵

- `transform` -移动、旋转对象
- `boolean_operation` -联合、差异、交叉
- `fillet_edge` -圆形边缘
- `chamfer_edge` -倒角边缘
- `mirror` -跨平面镜像对象
- `scale` -均匀或非均匀缩放对象

### 文档管理

- `create_document` -创建新文档
- `list_documents` -列出打开的文档
- `list_objects` -列出文档中的对象

### 导出/导入

- `export_stl` -导出为STL格式
- 其他格式即将推出

______________________________________________________________________

## 📋 **用法示例**

### Python API

from src.mcp_freecad import FreeCADConnection, PrimitiveToolProvider

Create connection (auto-selects best method)

fc = FreeCADConnection(auto_connect=True)

if fc.is_connected(): print(f"Connected via: {fc.get_connection_type()}")

# Create a document doc_name = fc.create_document("MyProject")

# Create objects box = fc.create_box(length=20, width=10, height=5) cylinder = fc.create_cylinder(radius=3, height=10)

# Export fc.export_stl(box, "my_box.stl")

### 工具提供程序使用情况

from src.mcp_freecad.tools.primitives import PrimitiveToolProvider

Initialize tool provider

primitives = PrimitiveToolProvider()

Execute tools

result = await primitives.execute_tool("create_box", { "length": 10.0, "width": 5.0, "height": 3.0 })

print(f"Created: {result.result['object_id']}")

### MCP服务器集成

from src.mcp_freecad.core.server import MCPServer from src.mcp_freecad import TOOL_PROVIDERS

Setup server

server = MCPServer()

Register tool providers

server.register_tool("primitives", TOOL_PROVIDERS["primitives"]()) server.register_tool("model_manipulation", TOOL_PROVIDERS["model_manipulation"]())

Initialize and run

await server.initialize()

______________________________________________________________________

## ⚙️ **配置**

### 基本配置(`config.json`)

{ "server": { "name": "mcp-freecad-server", "version": "0.7.11" }, "freecad": { "connection_method": "auto", "host": "localhost", "port": 12345, "freecad_path": "freecad" }, "tools": { "enable_primitives": true, "enable_model_manipulation": true, "enable_export_import": true } }

### 连接方法配置

{ "freecad": { "connection_method": "launcher", "use_apprun": true, "apprun_path": "/path/to/squashfs-root/AppRun", "script_path": "/path/to/freecad_launcher_script.py" } }

______________________________________________________________________

## 🔧 **发展**

### 项目结构

- **`src/mcp_freecad/`** -主包装
- **`freecad-ai/`** -FreeCAD图形用户界面插件
- **`tests/`** -测试套件
- **`docs/`** -文件
- **`scripts/`** -设置和实用程序脚本

### 添加新工具

1. 在中创建新的工具提供程序 `src/mcp_freecad/tools/`
1. 从……继承…… `ToolProvider` 基类
1. 实施所需方法(`tool_schema`, `execute_tool`)
1. 注册 `TOOL_PROVIDERS` 在 `__init__.py`

from .base import ToolProvider, ToolResult, ToolSchema

class MyToolProvider(ToolProvider): @property def tool_schema(self) -> ToolSchema: return ToolSchema( name="my_tool", description="My custom tool", parameters={...}, returns={...} )

async def execute_tool(self, tool_id: str, params: Dict[str, Any]) -> ToolResult: # Implementation return self.format_result(status="success", result=result)

### 测试

Run tests

python -m pytest tests/

Run with coverage

python -m pytest tests/ --cov=src --cov-report=html

Run specific test

python -m pytest tests/test_primitives.py -v

______________________________________________________________________

## 🐳 **Docker支持**

Build and run with Docker Compose

docker compose up

Build from scratch

docker compose build --no-cache docker compose up

______________________________________________________________________

## 📚 **文档**

- [FreeCAD集成指南](docs/FREECAD_INTEGRATION.md)
- [连接方法](docs/CONNECTION_METHODS.md)
- [工具开发](docs/TOOL_DEVELOPMENT.md)
- [配置参考](docs/CONFIGURATION.md)

______________________________________________________________________

## 🤝 **贡献**

1. 分叉存储库
1. 创建要素分支
1. 进行更改
1. 添加测试
1. 提交拉取请求

______________________________________________________________________

## 📄 **许可证**

此项目根据MIT许可证获得许可-请参阅 [许可证](LICENSE) 文件以获取详细信息。

______________________________________________________________________

## 🙏 **致谢**

- FreeCAD开发团队为优秀的CAD软件
- 模型上下文协议（MCP）框架的拟人化
- 贡献者和社区成员

______________________________________________________________________

🛠️ MCP-FreeCAD Integration - Bridging AI and CAD through advanced connectivity

Crafted with ❤️ by jango-blockchained • 2025