使用说明

FreeCAD MCP

FreeCAD MCP公开了一个模型上下文协议（MCP）服务器，该服务器通过此存储库中提供的XML-RPC插件驱动正在运行的FreeCAD会话。服务器将常见的CAD操作打包为MCP工具，可以捕获活动3D视图的屏幕截图，并记录每个工具的指标，以便您可以审核代理如何与模型交互。

路径	描述
`src/freecad_mcp/server.py`	FastMCP服务器、工具定义、度量助手和 `freecad-mcp` CLI入口点。
`src/freecad_mcp/py.typed`	将包标记为已键入，以便进行静态类型检查器。
`addon/FreeCADMCP/`	FreeCAD工作台，添加了一个工具栏启动/停止RPC服务器命令。
`addon/FreeCADMCP/rpc_server/rpc_server.py`	XML-RPC桥，公开文档/对象操作、屏幕截图和零件库帮助程序。
`addon/FreeCADMCP/rpc_server/serialize.py`	将FreeCAD文档对象转换为JSON友好结构。
`addon/FreeCADMCP/rpc_server/parts_library.py`	围绕官方FreeCAD的便利包装 `parts_library` 插件
`pyproject.toml`, `uv.lock`	项目元数据和锁定依赖版本（Python>=3.12， `mcp[cli]`).

使用 uv （建议使用，因为提供了锁定文件）：

uv venv
.\.venv\Scripts\Activate.ps1
uv pip install -e .

与平原 pip:

python -m venv .venv
.\.venv\Scripts\activate
pip install -e .

复制 addon/FreeCADMCP 到您的FreeCAD Mod 目录（例如。， %APPDATA%\FreeCAD\Mod\FreeCADMCP 在Windows上）。
重新启动FreeCAD并切换到 MCP插件 工作台。
使用工具栏/菜单命令 启动RPC服务器 在从MCP服务器连接之前。该插件正在监听 localhost:9875 默认情况下，使用 QtCore.QTimer 以处理排队的GUI工作。
（可选）安装官方 parts_library 附加组件，以便 insert_part_from_library 和 get_parts_list 可以浏览和插入 .FCStd 资产。

在FreeCAD加载项运行后启动服务器：

uv run freecad-mcp --host localhost --port 9875 --timeout 30 --metrics-file metrics.csv

有用的标志：

服务器启动后，连接任何MCP客户端，例如：

mcp run freecad-mcp

（见 mcp CLI文档，了解配置传输/auth的详细信息。)

工具	目的
`create_document`	创建新的FreeCAD文档并报告成功/失败。
`create_object`	插入带有属性和可选屏幕截图的Part/Draft/PartDesign/Fem对象。
`edit_object`	更新对象属性并捕获当前三维视图。
`delete_object`	从文档中删除对象。
`execute_code`	在FreeCAD中运行任意Python并返回控制台消息+预览。
`get_view`	请求常见相机方向（等距、正面、顶部等）的屏幕截图。
`insert_part_from_library`	将FreeCAD零件库中的零件合并到活动文档中。
`get_objects`	从文档中转储所有对象（序列化为JSON）以及屏幕截图。
`get_object`	检查具有详细序列化属性的单个对象。
`get_parts_list`	列出库中可用零件的相对路径。
`get_metrics_summary`	读取服务器在内存中收集的聚合计数器。
`reset_metrics`	在不接触CSV文件的情况下重置内存中的计数器。

asset_creation_strategy -代理在修改模型之前可以请求的分步说明。它鼓励查询当前文档，优先选择零件库资源，并使用验证编辑 get_object.

每次工具调用都会被计时并附加到由定义的CSV中 --metrics-file。内存中的摘要通过以下方式公开 get_metrics_summary.
屏幕截图使用 FreeCADGui.ActiveDocument.ActiveView.saveImage。如果视图无法生成图像（例如TechDraw），则工具会退回到有用的文本注释。
连接问题通常意味着FreeCAD插件未运行或绑定到其他主机/端口。请检查FreeCAD控制台的“RPC服务器已启动”日志，然后重新启动MCP服务器。