FreeCAD MCP 架构全解双组件 XML-RPC 桥接看懂 AI 控制 CAD 全链路【免费下载链接】freecad-mcpFreeCAD MCP(Model Context Protocol) server项目地址: https://gitcode.com/gh_mirrors/fr/freecad-mcpFreeCAD MCP 是一款让你用 Claude Desktop 等 AI 客户端直接控制 FreeCAD 的 MCPModel Context Protocol服务器。它由FreeCAD 内运行的 RPC 插件 独立启动的 MCP 服务器两个组件组成中间通过本地 XML-RPC 协议桥接实现创建零件、执行 Python 脚本、截图反馈、FEM 仿真等完整的 AI 控制 CAD 链路。本文带你一次看懂这套架构的每个环节。架构一页看懂AI 到 CAD 的数据流整个系统只有一条通信主线理解它就理解了全部AI 客户端 (Claude Desktop 等) │ MCP 协议工具调用 / 文本图片响应 ▼ MCP 服务器 freecad-mcpuvx 独立启动Python 3.12 │ XML-RPC默认 localhost:9875 ▼ FreeCAD 插件 FreeCADMCPXML-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 客户端能理解的工具模块职责src/freecad_mcp/server.py注册 create_object、execute_code、get_view 等全部 MCP 工具src/freecad_mcp/freecad_client.pyXML-RPC 客户端处理超时、认证令牌、版本握手src/freecad_mcp/operations/core.py把 RPC 结果转换为文本 截图的工具响应src/freecad_mcp/headless.py无头 freecadcmd 子进程执行每个操作完成后服务器会顺带请求一张 3D 视图截图base64 编码 PNG随文本一起返回——这就是 AI看见模型、持续修正设计的闭环所在。XML-RPC 桥接全链路 5 步拆解以让 AI 画一个盒子为例一次调用的完整旅程AI 客户端决定调用create_object工具MCP 协议携带参数发出请求MCP 服务器收到工具调用经 src/freecad_mcp/freecad_client.py 的FreeCADConnection以 XML-RPC 发往localhost:9875插件 RPC 线程收到请求调用dispatch_to_gui把创建任务丢给 GUI 线程队列FreeCAD GUI 线程真正执行addObjectrecompute生成几何体响应原路返回结果文本 等轴测截图一路传回 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.mdGUI/后台/无头三种执行方式与超时排障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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考