企业官网建设流程全解析

FreeCAD MCP 架构全解：双组件 + XML-RPC 桥接，看懂 AI 控制 CAD 全链路

【免费下载链接】freecad-mcpFreeCAD MCP(Model Context Protocol) server项目地址: https://gitcode.com/gh_mirrors/fr/freecad-mcp

FreeCAD MCP 是一款让你用 Claude Desktop 等 AI 客户端直接控制 FreeCAD 的 MCP（Model Context Protocol）服务器。它由"FreeCAD 内运行的 RPC 插件 + 独立启动的 MCP 服务器"两个组件组成，中间通过本地 XML-RPC 协议桥接，实现创建零件、执行 Python 脚本、截图反馈、FEM 仿真等完整的 AI 控制 CAD 链路。本文带你一次看懂这套架构的每个环节。

架构一页看懂：AI 到 CAD 的数据流

整个系统只有一条通信主线，理解它就理解了全部：

AI 客户端 (Claude Desktop 等) │ MCP 协议（工具调用 / 文本+图片响应） ▼ MCP 服务器 freecad-mcp（uvx 独立启动，Python 3.12+） │ XML-RPC（默认 localhost:9875） ▼ FreeCAD 插件 FreeCADMCP（XML-RPC 服务器线程） │ GUI 线程分发（dispatch_to_gui） ▼ FreeCAD 文档树 / 3D 视图 ──截图(base64 PNG)──► 原路返回给 AI

关键事实：两个组件使用各自独立的 Python 环境——插件跑在 FreeCAD 自带的 Python 里，MCP 服务器跑在uv/uvx提供的 Python 3.12 环境中，互不干扰（见 docs/installation.md）。

组件一：FreeCAD 内的 RPC 插件

插件源码位于 addon/FreeCADMCP/，它向 FreeCAD 注册了一个名为MCP Addon的工作台（addon/FreeCADMCP/InitGui.py），工具栏提供 6 个命令：Start/Stop RPC Server、自动启动、远程连接开关、允许 IP 配置、认证令牌设置。

点击Start RPC Server后，插件在后台线程启动一个带 IP 过滤的 XML-RPC 服务器（默认 9875 端口），状态栏会显示启动成功信息：

插件的核心是 addon/FreeCADMCP/rpc_server/rpc_server.py 中的FreeCADRPC类，它注册了所有 RPC 方法：create_document、create_object、execute_code、get_active_screenshot、run_fem_analysis等。

GUI 线程分发：架构里最关键的一招

XML-RPC 服务器运行在自己的线程，但 FreeCAD 的文档树和 3D 视图只能由 GUI 主线程操作。于是 addon/FreeCADMCP/rpc_server/gui_dispatch.py 实现了一个任务队列：RPC 线程把任务入队，通过 Qt 信号立即唤醒 GUI 线程执行，并等待结果返回。它还有几个贴心的保护机制：

• 每调用独立响应队列：一次调用超时不会污染下一次调用的结果
• 鼠标按键保护：你正在拖拽旋转 3D 视图时，MCP 任务会短暂让路，不打断操作
• 卡死快速失败：某个任务卡住后，后续调用立即报错而不是无限等待

组件二：独立运行的 MCP 服务器

MCP 服务器源码位于 src/freecad_mcp/，通过uvx freecad-mcp一行命令启动（依赖定义见 pyproject.toml）。它基于 FastMCP 框架，把插件的 RPC 能力包装成 AI 客户端能理解的"工具"：

每个操作完成后，服务器会顺带请求一张 3D 视图截图（base64 编码 PNG）随文本一起返回——这就是 AI"看见"模型、持续修正设计的闭环所在。

XML-RPC 桥接：全链路 5 步拆解

以"让 AI 画一个盒子"为例，一次调用的完整旅程：

1. AI 客户端决定调用create_object工具，MCP 协议携带参数发出请求
2. MCP 服务器收到工具调用，经 src/freecad_mcp/freecad_client.py 的FreeCADConnection以 XML-RPC 发往localhost:9875
3. 插件 RPC 线程收到请求，调用dispatch_to_gui把创建任务丢给 GUI 线程队列
4. FreeCAD GUI 线程真正执行addObject+recompute，生成几何体
5. 响应原路返回：结果文本 + 等轴测截图一路传回 AI，模型"看到"成果后继续下一步

三种代码执行方式怎么选

这是使用中最常踩坑的地方，三条通道各有分工：

• execute_code：全程在 GUI 线程执行，默认 90 秒预算，是普通自动化的安全默认
• execute_code_async：重几何运算（布尔、放样）放后台线程跑，通过注入的commit(fn)把文档写操作交回 GUI 线程，用完可查任务状态
• execute_code_headless：在独立的freecadcmd无头进程中跑脚本（见 src/freecad_mcp/headless.py），就算 OCCT 原生崩溃也只会杀掉子进程，GUI 安然无恙，之后用reload_document把磁盘上的结果读回界面

从一张 2D 工程图还原成 3D 模型的例子就综合用到了这些能力：

安全与版本握手：别忽略的细节

• 默认只听 localhost：远程访问需手动开启，且建议配合 IP 白名单 + 认证令牌（addon/FreeCADMCP/rpc_server/ip_filter.py 还会拒绝网页脚本发起的请求，防 CSRF/DNS 重绑定）
• 版本握手：MCP 服务器连接时调用get_rpc_status比对插件与服务端版本，不匹配会在响应中附带升级警告（src/freecad_mcp/version.py）
• 故障可见：get_rpc_status工具不占用 GUI 线程，即使 GUI 卡死也能查出是哪个操作卡住、是否需要重启 FreeCAD

启动失败时状态栏会给出明确的错误提示，方便排查端口占用等问题：

延伸阅读：按路径找资料

• 安装与目录定位：docs/installation.md
• 自动启动、远程连接、认证令牌配置：docs/configuration.md
• 全部工具清单与 FEM 分析说明：docs/tools.md
• GUI/后台/无头三种执行方式与超时排障：docs/execution.md
• 设计演示与 ADK、LangChain 集成示例：docs/examples.md
• 本地 FEM 弯梁分析示例脚本：examples/cantilever_fem.py

想要动手跑起来，先安装 FreeCAD 与 uv，然后：

git clone https://gitcode.com/gh_mirrors/fr/freecad-mcp cd freecad-mcp

把addon/FreeCADMCP复制进 FreeCAD 的 Mod 目录重启，MCP 端在客户端配置里填上uvx freecad-mcp即可。至此，AI 控制 CAD 的双组件 + XML-RPC 桥接全链路你已经完整掌握：插件负责"在 FreeCAD 里动手"，MCP 服务器负责"把能力讲给 AI 听"，XML-RPC + GUI 线程分发则是让这套系统既快又稳的桥。

【免费下载链接】freecad-mcpFreeCAD MCP(Model Context Protocol) server项目地址: https://gitcode.com/gh_mirrors/fr/freecad-mcp