FreeCAD MCP

freecad-mcp

这个工具能做什么

这是 AI Agent 与 FreeCAD 之间的桥梁，能为参数化设计、CNC 刀具路径生成和网格处理提供思路。你负责提出设计意图并做出领域判断，Agent 负责处理 FreeCAD 的具体操作。协作起来，可以加快工作进度，共同设计那些手工制作需要数小时的东西，理清 FreeCAD 擅长生成的晦涩错误信息，还能找出那些独自几乎不可能发现的隐蔽、棘手的建模问题。这个工具是为日常个人使用而打造的，适用于设计零件、生成刀具路径、打印和切割，而非演示。完整的工具参考请参阅 TOOLS.md。

可以一起完成的工作

• 梳理设计方案——“我需要一块安装板，尺寸为 100x60mm，有四个 M3 孔，边角倒圆。什么方案合适？”你提出需求和约束；Agent 负责建模、指出未明确的决策，并与你反复迭代。
• 诊断问题——“我刚刚尝试拉伸这个草图，结果很奇怪——FreeCAD 到底在告诉我什么？”Agent 可以读取 Report View、检查草图约束，并用你能据此采取行动的方式解释当前情况。
• 改进现有零件——“这面墙好像太薄了，而且圆角可能无法经受打印——我们一起看看吧。”
• 规划 CNC 刀具路径——“我想铣削这个凹槽——我们一起为这种材料选合适的刀具和参数吧。”
• 制作可复用的工具——“我每次做支架都要重复这个工作流——我们编写一个宏，从尺寸表格生成这些支架吧。”
• 提交前检查成果——“这个模型有几何错误吗？”“这些墙能经受打印吗？”“这些零件会互相碰撞吗？”
• 处理网格——“我有制造商提供的 STL 文件——我们把它导入 FreeCAD 并添加安装结构吧。”
• 导出用于制造——“把它导出为 STEP，并为我的 CNC 铣床生成 G-code。”

实际效果

下面是我使用 MCP 的几个示例。

调试损坏的外部引用——FreeCAD 无法恢复的链接、看似与你对模型的了解相矛盾的错误信息，以及通过直接读取文件找到的一行修复方案。

完整故事 →

---

设计屋顶瓦生成器——经过几轮讨论，设计出一个参数化生成器，可根据参数表格为任意屋顶表面铺设瓦片。

完整故事 →

---

入门指南

FreeCAD 版本支持： 除 CAM 以外的所有工具都支持 FreeCAD 1.1.x（当前稳定版）。CAM 刀具路径生成需要使用当前的 FreeCAD 每周开发版（上游改用基于日历的版本号之前称为“1.2-dev”，例如 26.3.x）——Path 工作台 API 在 1.1 与开发版系列之间发生了不兼容的变更。本项目跟进最新的每周版本。

本项目在 macOS 上使用 Claude Code 开发。代码支持 macOS、Windows 和 Linux——其他平台应该也能运行，但测试较少。我们会考虑其他 Agent 和平台相关的 PR。此外，我们还使用 LM Studio 的原生 MCP 客户端（qwen/qwen2.5-coder-14b、qwen/qwen3-32b、google/gemma-4-e4b）进行了手动冒烟测试，以确认协议在 Claude 之外也能正常往返——详情和注意事项请参阅 AGENT-INSTALL.md。

告诉你的 AI Agent：

前往 https://github.com/blwfish/freecad-mcp 并阅读 AGENT-INSTALL.md 文件。按照说明在此机器上安装和配置 FreeCAD MCP 服务。

你的 Agent 会处理剩下的所有工作——安装先决条件、克隆仓库、设置 FreeCAD 插件并完成注册。设置完成后，你就可以让 Agent 设计零件。

验证安装

FreeCAD 运行且已加载 AICopilot 工作台后，打开 Report View（菜单：View → Panels → Report View）。你应该会看到类似以下内容：

关于此输出，有几点值得了解：

• AI Copilot Service starting — 确认 AICopilot 工作台已正确加载。如果看不到此消息，说明插件未安装，或 FreeCAD 未能找到它。
• Debug/crash infrastructure loaded — 活动监测工具正在运行。如果操作过程中出现问题，日志和崩溃报告会自动捕获。
• Socket server started / Claude ready — 桥接服务正在监听。这行消息表示你的 AI Agent 可以连接。
• Font alias warning（橙色）— 无害的 Qt 提示，大多数 macOS 系统上都会出现，与当前操作无关。这不是问题。

运行多个 FreeCAD 实例

MCP 可以同时与多个 FreeCAD 实例通信——这适用于比较本地调试版本与标准发行版、在旁边窗口中运行回归测试并保持主工作区打开，或在同一个 Claude 会话中驱动无头工作进程。

每个 FreeCAD 进程（GUI 或无头）都会在启动时生成一个 UUID，在 /tmp/freecad_mcp_<uuid>.sock 创建自己的套接字，并将发现文件写入 ~/.cache/freecad-mcp/instances/<uuid>.json。桥接服务会扫描此目录以查找运行中的实例，无论这些实例由谁启动。

启动时的可选环境变量：

• FREECAD_MCP_LABEL=<name> — 为实例指定一个易读的名称（否则默认为 UUID）
• FREECAD_MCP_SOCKET=<path> — 完全覆盖套接字路径（适用于 CI / 脚本严格控制的启动流程）

从 Agent 列出实例并切换：

list_freecad_instances          # all live instances + active doc info
select_freecad_instance uuid=<id>           # by uuid
select_freecad_instance label="weekly"      # or by label

从 Agent 启动实例：

spawn_freecad_instance gui=true label="private" \
    freecad_binary=/path/to/your/private/build/bin/FreeCAD
spawn_freecad_instance gui=true label="weekly" \
    freecad_binary=/Applications/FreeCAD.app/Contents/MacOS/FreeCAD

未明确选择实例时的解析规则：0 个运行中的实例 → 报错；1 个运行中的实例 → 自动选择；2 个或更多运行中的实例 → 报错并列出实例（调用 select_freecad_instance）。

开发者指南

# Unit tests (1430 tests, no FreeCAD required)
python3 -m pytest tests/unit/

# Integration tests (147 tests, requires running FreeCAD with AICopilot loaded)
python3 -m pytest tests/integration/

# All tests with coverage
python3 -m pytest --cov=AICopilot

提示词缓存与直接调用 Claude API

**对于 Claude 用户：最简单、最省钱的方式是直接使用 Claude Code、Web 界面或 CLI 工具。**这些平台会自动处理提示词缓存和成本优化，你无需操心。如果你只是使用此 MCP 在 FreeCAD 中设计零件，请使用 Claude Code。无需继续阅读本节。

如果你正在构建会直接调用 Claude API（使用 Anthropic SDK）的应用或集成，就必须了解提示词缓存。Claude 桌面应用、Web 界面和 CLI 工具会自动缓存文件上下文和工具引用——你看不到这项优化，但它能降低基于相同上下文重复查询时的延迟和成本。

直接调用 API 时，必须显式管理缓存。MCP 服务本身不会调用 API，但如果你要构建会调用 API 的集成或扩展：

• 在部署前阅读 Anthropic SDK 文档，了解提示词缓存
• 了解缓存 TTL（通常为 5 分钟）和成本影响（占输入令牌的 20%）
• 请注意，缓存键包含模型、系统提示词和精确的令牌边界——细微差异也会导致缓存失效
• 如果上下文频繁更新（例如文档状态快照），请考虑缓存失效风险

同样，如果你在工作流中集成其他 MCP 服务或 Agent，它们也可能存在 README 中未记录的类似注意事项。请查看其文档或源代码，了解缓存行为、异步任务处理和令牌限制——不要假设它们的工作方式与 Claude Code 相同。

测试套件通过单元测试覆盖处理程序分发层、基础设施和文档操作，并通过针对运行中的 FreeCAD 实例的集成测试，端到端覆盖 Part、PartDesign、Sketch、Draft、Boolean、Transform、Measurement 和 CAM 工作流。CI 会在每次推送时运行这两个测试套件。

内置诊断

MCP 包含操作日志记录、崩溃捕获和报告视图访问功能。FreeCAD 自带的错误报告往往晦涩难懂——OCCT 内核崩溃不会留下任何痕迹，而出现的错误消息也需要结合上下文才能解读。这些工具能提供所需的上下文。

大多数用户和开发者只有在需要时才会知道这套基础设施的存在。请参阅 docs/diagnostics.md，其中包含完整指南和真实示例；当出现问题时，Agent 应遵循的逐步调查流程请参阅 AGENT-DEBUGGING.md。

完整的技术细节、架构、贡献指南以及如何添加新工具，请参阅 AGENT-INSTALL.md。

安全

此工具会授予你的 AI Agent 对 FreeCAD Python 环境的完整访问权限，包括文件系统和操作系统——这是有意为之。这也意味着 Agent 会将文档内容（对象标签、宏源码、电子表格值）直接读入其推理上下文，因此对待来自不可信来源的 FreeCAD 文件，应与对待不可信代码一样谨慎。完整的安全模型、实用的缓解措施以及漏洞报告方式，请参阅 SECURITY.md。

MCP 还会每天检查一次 GitHub 是否有更新版本——它会向 GitHub 公共 API 发起普通拉取请求，将结果缓存并记录在本地的 ~/.cache/freecad-mcp/version_check.log 中，以便审计。详情请参阅 SECURITY.md。

问题反馈

如果遇到 Bug，请提交问题——无声失败对任何人都没有帮助。Agent 不会告诉你哪里出了问题；它们只会让任务失败。什么样的问题报告才有用，请参阅 CONTRIBUTING.md。

许可证

LGPL-2.1-or-later