theosib/freecad-mcp-server

开发工具

本页由 AI 翻译，技术细节请以原文为准。查看原文

37 stars 5 forks 质量 58 趋势 12

Repository Install

MCP 服务器允许 Claude Code 直接与 FreeCAD 通信，检查和修改状态

概览

一个MCP（模型上下文协议）服务器，连接Claude与一个实时的FreeCAD实例。它让Claude能够深入访问FreeCAD的运行时状态——文档结构、对象属性、形状拓扑、草图约束健康等——支持AI辅助的CAD工作和FreeCAD开发调试。与简单的脚本执行MCP服务器不同，这个项目让Claude能够真正理解FreeCAD内部发生的事情： 1. （freecad_addon/） — 运行于 FreeCAD 内部作为工作台。启动一个线程 TCP 服务器，接受 JSON-RPC 请求，并通过 QTimer 轮询的工作队列在 FreeCAD 主线程上执行。 2. （src/freecad_mcp_agent/） — 由 Claude 通过 stdio 生成。通过 TCP 连接到插件，并将 MCP 工具调用转换为 JSON-RPC 请求。 FreeCAD在macOS上不可靠地跟随符号链接，所以我们用一个薄加载文件。 - macOS：~/Library/Application Support/FreeCAD/Mod/（或 ~/Library/Application Support/FreeCAD/v1-2/Mod/ 用于每周构建）- Linux：~/。

概述（AI 翻译）

一个MCP（模型上下文协议）服务器，连接Claude与一个实时的FreeCAD实例。它让Claude能够深入访问FreeCAD的运行时状态——文档结构、对象属性、形状拓扑、草图约束健康等——支持AI辅助的CAD工作和FreeCAD开发调试。

它的作用

与简单的脚本执行MCP服务器不同，这个项目提供了丰富的上下文提取，让Claude真正理解FreeCAD内部发生了什么：

工具	它返回的内容
`list_documents`	所有已打开的文档，包含名称、文件路径、对象数量
`get_document_graph`	完整特征树——每个具有TypeId、属性、依赖链接、有效性状态的对象
`inspect_object`	单个对象的完整属性转储，包含形状元数据
`analyze_shape`	拓扑分析——面分类（平面/圆柱/圆锥等）、边细节、包围框、体积
`get_sketch_diagnostics`	约束健康 — 景深、冲突、冗余、每个约束和几何元素，含坐标
`tracked_recompute`	用前后差分重新计算 — 新错误、已解决错误、持续错误

本页由 AI 翻译，技术细节请以原文为准。

README

以下为原文 README 节选，完整内容请查看原文。

FreeCAD MCP Server

An MCP (Model Context Protocol) server that bridges Claude with a live FreeCAD instance. It gives Claude deep access to FreeCAD’s runtime state — document structure, object properties, shape topology, sketch constraint health, and more — enabling AI-assisted CAD work and FreeCAD development debugging.

What It Does

Unlike simple script-execution MCP servers, this project provides rich context extraction that lets Claude genuinely understand what’s happening inside FreeCAD:

Tool	What It Returns
`list_documents`	All open documents with names, file paths, object counts
`get_document_graph`	Full feature tree — every object with TypeId, properties, dependency links, validity state
`inspect_object`	Complete property dump for a single object, with shape metadata
`analyze_shape`	Topological analysis — face classifications (Plane/Cylinder/Cone/…), edge details, bounding box, volume
`get_sketch_diagnostics`	Constraint health — DOF, conflicts, redundancies, every constraint and geometry element with coordinates
`tracked_recompute`	Recompute with before/after diff — new errors, resolved errors, persistent errors
`execute_script`	Run arbitrary Python inside FreeCAD (escape hatch for anything not covered above)
`get_screenshot`	Capture the 3D viewport as a base64 PNG
`reload_handlers`	Hot-reload handler code without restarting FreeCAD

Architecture

Claude (Code/Desktop)  ←stdio MCP→  Bridge Server  ←TCP:9876→  FreeCAD Addon
                                     (this project)              (inside FreeCAD)

The project has two components:

FreeCAD addon (freecad_addon/) — runs inside FreeCAD as a workbench. Starts a threaded TCP server that accepts JSON-RPC requests and executes them on FreeCAD’s main thread via a QTimer-polled work queue.
MCP bridge server (src/freecad_mcp_agent/) — spawned by Claude via stdio. Connects to the addon over TCP and translates MCP tool calls into JSON-RPC requests.

Installation

1. Install the MCP bridge

# Clone the repo
git clone https://github.com/theosib/FreeCAD-MCP-Server.git
cd FreeCAD-MCP-Server

# Create a venv and install
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Install the FreeCAD addon

FreeCAD doesn’t reliably follow symlinks on macOS, so we use a thin loader file.

Find your FreeCAD Mod directory:

macOS: ~/Library/Application Support/FreeCAD/Mod/ (or ~/Library/Application Support/FreeCAD/v1-2/Mod/ for weekly builds)
Linux: ~/.local/share/FreeCAD/Mod/
Windows: %APPDATA%/FreeCAD/Mod/

Tip: Run FreeCAD.getUserAppDataDir() in FreeCAD’s Python console to find the exact path.

Create the loader:

mkdir -p "/FreeCADMCPAgent"

Create /FreeCADMCPAgent/InitGui.py with:

import sys

在 GitHub 查看完整 README

安装

This server does not publish a one-line install command.

Open the repository installation guide 新手？先看 mcpskill.org 教程 →

配置

{
  "mcpServers": {
    "freecad-debug": {
      "command": "/absolute/path/to/FreeCAD-MCP-Server/.venv/bin/freecad-mcp-agent",
      "env": {
        "FREECAD_MCP_HOST": "127.0.0.1",
        "FREECAD_MCP_PORT": "9876"
      }
    }
  }
}