Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@FreeCAD MCP Server Check if Sketch001 is fully constrained and list any conflicts."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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 |
| All open documents with names, file paths, object counts |
| Full feature tree — every object with TypeId, properties, dependency links, validity state |
| Complete property dump for a single object, with shape metadata |
| Topological analysis — face classifications (Plane/Cylinder/Cone/...), edge details, bounding box, volume |
| Constraint health — DOF, conflicts, redundancies, every constraint and geometry element with coordinates |
| Recompute with before/after diff — new errors, resolved errors, persistent errors |
| Run arbitrary Python inside FreeCAD (escape hatch for anything not covered above) |
| Capture the 3D viewport as a base64 PNG |
| Hot-reload handler code without restarting FreeCAD |
Related MCP server: freecad-mcp
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.
# 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 .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 "<your-mod-dir>/FreeCADMCPAgent"Create <your-mod-dir>/FreeCADMCPAgent/InitGui.py with:
import sys
_ADDON_DIR = "/absolute/path/to/FreeCAD-MCP-Server/freecad_addon"
if _ADDON_DIR not in sys.path:
sys.path.insert(0, _ADDON_DIR)
_project_init = _ADDON_DIR + "/InitGui.py"
_ns = dict(globals())
_ns["__file__"] = _project_init
with open(_project_init) as _f:
exec(compile(_f.read(), _project_init, "exec"), _ns)Replace /absolute/path/to/FreeCAD-MCP-Server with the actual path to your clone.
Add a .mcp.json to your working directory (or FreeCAD source tree):
{
"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"
}
}
}
}Start FreeCAD. The RPC server auto-starts on port 9876 (you'll see "MCP Debug Agent: RPC server auto-started" in FreeCAD's console). Set FREECAD_MCP_NO_AUTOSTART=1 to disable auto-start.
Launch Claude Code in a directory with the .mcp.json config.
Use the tools. Claude can now inspect your FreeCAD model:
"What objects are in the current document?"
"The Pocket001 feature looks wrong — can you diagnose it?"
"Is Sketch003 fully constrained? Are there any conflicts?"
"Recompute the document and tell me what changed."
This project was designed for debugging FreeCAD itself. When the .mcp.json is placed in a FreeCAD source tree, Claude Code gets simultaneous access to:
Source code — C++ and Python files, git history, build system (via Claude Code's native file access)
Live runtime state — object properties, shape topology, constraint solver state (via MCP tools)
This lets Claude correlate what the code should do with what the runtime actually produced. See docs/freecad-fork-instructions.md for detailed workflows and a TypeId-to-source-file mapping table.
Variable | Default | Purpose |
|
| RPC server host |
|
| RPC server port |
| (unset) | Set to |
FreeCAD-MCP-Server/
├── pyproject.toml # Python package config
├── src/freecad_mcp_agent/
│ ├── server.py # MCP server (stdio, all tool definitions)
│ └── bridge.py # TCP client connecting to FreeCAD addon
├── freecad_addon/
│ ├── InitGui.py # Workbench registration + auto-start
│ ├── mcp_commands.py # Start/Stop commands, handler registration
│ ├── rpc_server.py # Threaded TCP server + main-thread dispatch
│ ├── package.xml # FreeCAD addon metadata
│ └── handlers/
│ ├── document.py # list_documents, get_document_graph
│ ├── inspection.py # inspect_object, analyze_shape
│ ├── sketcher.py # get_sketch_diagnostics
│ ├── recompute.py # tracked_recompute
│ ├── execution.py # execute_script
│ └── viewport.py # get_screenshot
└── docs/
└── freecad-fork-instructions.mdLGPL-2.1-or-later (same as FreeCAD)
Detailed topological analysis of an object's shape.
Returns shape type, volume, area, center of mass, bounding box, topology counts (vertices/edges/faces/solids), face classifications (plane/cylinder/cone/sphere/toroid with parameters), and edge details.
Use this to understand the geometric result of a feature — especially useful for diagnosing why a boolean or pocket operation produced unexpected geometry.
Args: name: Object name that has a Shape (e.g., "Pad001", "Cut001"). doc_name: Document name. Empty string uses the active document.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| doc_name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It implies a read-only analysis by describing returns but does not explicitly state that the tool does not modify the state. The description is adequate but could be more transparent about side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively concise with two paragraphs plus an Args section. It is well-structured and front-loaded with the purpose. However, the first paragraph is a list of returns that could be slightly more streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description comprehensively lists all return values and explains usage context. It fully covers what the tool does and why to use it, leaving no major gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, but the description explains that 'name' is an object with a Shape (e.g., 'Pad001') and 'doc_name' is the document name with empty string defaulting to active document. This adds meaningful context beyond the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Detailed topological analysis of an object's shape' and enumerates specific return values (shape type, volume, area, etc.), distinguishing it from sibling tools like get_sketch_diagnostics or inspect_object by focusing on shape geometry from operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using this tool to 'understand the geometric result of a feature — especially useful for diagnosing why a boolean or pocket operation produced unexpected geometry.' This provides clear context, though it does not explicitly mention when not to use it or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute arbitrary Python code in FreeCAD's interpreter context.
The script has access to: FreeCAD, FreeCADGui, App, Gui, doc (active document). Stdout and stderr are captured and returned.
Use this as an escape hatch for operations not covered by the specific tools above. For example: creating objects, modifying properties, running macros, or accessing FreeCAD APIs not yet exposed as tools.
Args: script: Python code to execute.
| Name | Required | Description | Default |
|---|---|---|---|
| script | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that stdout and stderr are captured and returned. It also lists available objects in the context. However, it does not warn about potential side effects like document corruption or performance impacts, but given the absence of annotations, it provides reasonable transparency about the tool's capabilities.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (about 6 sentences) and well-structured. It front-loads the purpose, then details context, usage guidance, and arguments. Every sentence is meaningful with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of annotations, the description covers the essential aspects: what it does, available context, usage guidance, and parameter meaning. It could mention error handling or synchronous execution, but overall it is sufficiently complete for an escape hatch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, requiring the description to provide meaning. The description adds value by explaining that the script runs in FreeCAD's interpreter with access to objects like FreeCAD, App, Gui, and doc. The 'Args: script: Python code to execute.' line is minimal but the broader context sufficiently enhances understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute arbitrary Python code in FreeCAD's interpreter context.' It identifies the specific verb (execute) and resource (Python code in FreeCAD), distinguishing itself from the sibling tools which are for analysis, inspection, and document operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly guides when to use this tool: 'Use this as an escape hatch for operations not covered by the specific tools above.' It also provides concrete examples (creating objects, modifying properties, running macros) that help the agent decide when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a structured representation of a document's feature tree.
Returns every object with its TypeId, label, properties, dependency links (InList/OutList), validity state, and touch state. This is the primary tool for understanding what a FreeCAD model contains.
Args: doc_name: Document name. Empty string uses the active document.
| Name | Required | Description | Default |
|---|---|---|---|
| doc_name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It implies a read-only operation by describing the return structure but does not explicitly state that it has no side effects, authorization requirements, or performance implications. The disclosure is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with no wasted words. It front-loads the purpose and return details, then provides parameter help. Every sentence adds value, and the structure logically flows from what the tool does to how to use it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter, no output schema, and no annotations, the description covers the essential aspects: what it returns and how to specify the document. It could add error handling (e.g., what happens if the document doesn't exist) or mention that the output is a tree, but overall it is sufficiently complete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter doc_name is described with context: 'Document name. Empty string uses the active document.' Since the input schema has no description (0% coverage), this adds meaningful information beyond the schema, clarifying the default behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets a structured representation of a document's feature tree and lists the returned fields (TypeId, label, properties, dependency links, validity/touch state). It also positions itself as the primary tool for understanding a FreeCAD model, distinguishing it from sibling tools like inspect_object or get_sketch_diagnostics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description calls it the 'primary tool for understanding what a FreeCAD model contains' but does not explicitly state when not to use it or provide alternatives. While the usage context is implied, there is no direct guidance on when to choose this over other tools like analyze_shape or inspect_object.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture the current 3D viewport as a base64-encoded PNG image.
Returns the image as a base64 string along with dimensions. Useful for visual inspection of the model state.
Args: width: Image width in pixels. height: Image height in pixels.
| Name | Required | Description | Default |
|---|---|---|---|
| width | No | ||
| height | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description explains return format and purpose. Could include more about error conditions or side effects, but sufficient for a screenshot tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two-sentence description plus concise Args section, no fluff, efficiently communicates essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately covers purpose, parameters, and return format for a simple tool with two optional parameters and no output schema. Minor gaps in error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions are empty (0% coverage), but description's Args section adds brief yet clear meaning to width and height parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool captures the current 3D viewport as a base64-encoded PNG image, distinguishing it from sibling tools like analyze_shape or execute_script.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions usefulness for visual inspection, providing clear context, but lacks explicit when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deep inspection of a sketch's constraint health.
Returns constraint count, geometry count, degrees of freedom, whether the sketch is fully constrained, and a detailed list of every constraint (type, value, referenced geometry indices, driving status, and whether it is redundant or conflicting).
Also returns geometry elements with type-specific details (line endpoints, circle centers/radii, arc parameters).
This is the primary diagnostic tool for sketch problems — over-constrained, under-constrained, or conflicting sketches.
Args: name: Sketch object name (e.g., "Sketch001"). doc_name: Document name. Empty string uses the active document.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| doc_name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It details the return values (list of constraints with types, values, status, etc.) but does not mention whether the tool is read-only, has side effects, or requires specific permissions. The absence of such behavioral context is a gap, though the diagnostic nature hints at safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a leading summary, a list of return contents, a usage statement, and parameter details. It is reasonably concise for the amount of detail, though a minor reduction in verbosity could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description thoroughly explains return values covering constraints and geometry. Parameters are fully described, and usage context is provided. For a diagnostic tool with two parameters, this is complete and leaves no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only parameter names and types with 0% description coverage. The tool description fully compensates by explaining each parameter: 'name: Sketch object name (e.g., 'Sketch001'). doc_name: Document name. Empty string uses the active document.' This adds essential semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'deep inspection of a sketch's constraint health' and enumerates specific outputs (constraint count, geometry count, degrees of freedom, etc.). It distinguishes itself as the primary diagnostic tool for sketch problems, differentiating it from siblings like 'analyze_shape' or 'inspect_object'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly positions the tool as 'the primary diagnostic tool for sketch problems — over-constrained, under-constrained, or conflicting sketches,' providing clear context on when to use it. It does not explicitly state when not to use or name alternatives, but the use case is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a full property dump and shape analysis for a single FreeCAD object.
Returns all properties (with types, groups, and documentation), dependency info, validity state, and basic shape metadata if the object has geometry.
Args: name: Object name (e.g., "Pad001", "Sketch002"). doc_name: Document name. Empty string uses the active document.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| doc_name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description mentions return content (properties, dependencies, validity, shape metadata) but does not explicitly state side effects, performance impact, or that it is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a one-line summary, structured bullet points for return values, and a clear 'Args' section. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low parameter count, no output schema, and no annotations, the description is fairly complete, covering purpose, parameters, and return content. Missing usage guidelines slightly reduce completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema lacks parameter descriptions (0% coverage). The description adds meaning by explaining 'name' and 'doc_name', including the default behavior of using the active document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a 'full property dump and shape analysis' for a single FreeCAD object, distinguishing it from siblings like analyze_shape which focuses solely on shape analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It only describes functionality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all open FreeCAD documents with their names, labels, file paths, object counts, and modification status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It adequately discloses the read-only nature and the fields returned, but does not mention any potential performance implications, required state of FreeCAD, or whether documents in all states are included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the action ('List all open FreeCAD documents') and efficiently enumerates the returned fields. Every part of the sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters and an output schema exists, reducing the burden on the description. The description covers the core functionality adequately, though it could mention edge cases like no open documents or documents with errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters (0 required, 100% coverage). With no parameters to document, the description does not need to add parameter semantics beyond what the schema provides. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all open FreeCAD documents and specifies the exact information returned (names, labels, file paths, object counts, modification status). This is a specific verb-resource combination with clear scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like get_document_graph or analyze_shape. There is no mention of prerequisites, expected context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hot-reload all FreeCAD addon handler modules.
Call this after editing handler code (in freecad_addon/handlers/) to pick up changes without restarting FreeCAD. Reloads all handler modules and re-registers them with the RPC server.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully bears the burden. It discloses that all handler modules are reloaded and re-registered with the RPC server. While it lacks mention of potential state loss, for a reload operation this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences. The first sentence contains the action and object, the second explains when to use it. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has zero parameters and no output schema, the description is complete. It covers the purpose, usage context, and behavior. There are no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, and the description correctly indicates no parameters are needed. Schema description coverage is 100% (none to cover), so the description adds value by explaining the zero-parameter behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Hot-reload all FreeCAD addon handler modules.' It specifies the verb 'reload' and the resource 'handler modules,' distinguishing it from sibling tools like analyze_shape or execute_script.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool: 'Call this after editing handler code (in freecad_addon/handlers/) to pick up changes without restarting FreeCAD.' It provides clear context and no alternative tools are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recompute a document and track what changed.
Snapshots every object's validity before recomputing, then diffs against the post-recompute state. Reports:
new_errors: objects that were valid before but are now invalid
resolved: objects that were invalid but are now valid
persistent_errors: objects that remain invalid
valid_count: number of objects that stayed valid
Use this instead of raw recompute to understand the impact of changes.
Args: doc_name: Document name. Empty string uses the active document.
| Name | Required | Description | Default |
|---|---|---|---|
| doc_name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description thoroughly explains the snapshot and diff process, including the four categories of reported changes. Does not mention potential side effects or performance, but sufficiently details the behavioral mechanism.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a clear opening, bulleted list for output, and a separate Args section. Concise without superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter and no output schema, the description fully covers input, behavior, and output format. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only parameter is doc_name. Schema provides no description, but the description adds 'Document name. Empty string uses the active document.', which adds essential meaning beyond schema defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Recompute a document and track what changed' with specific output metrics. Distinguishes itself from a raw recompute by highlighting the tracking capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises 'Use this instead of raw recompute to understand the impact of changes', providing clear guidance on when to select this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0analyze_shapeexecute_scriptget_document_graphget_screenshotget_sketch_diagnosticsinspect_objectlist_documentsreload_handlerstracked_recomputeEach tool has a distinct and clearly defined purpose with no overlap: analyze_shape for geometric analysis, execute_script for Python execution, get_document_graph for feature tree inspection, get_screenshot for visual capture, get_sketch_diagnostics for sketch constraints, inspect_object for property dumps, list_documents for document listing, reload_handlers for module reloading, and tracked_recompute for change tracking. The descriptions explicitly differentiate their use cases, eliminating ambiguity.
All tool names follow a consistent verb_noun pattern using snake_case, such as analyze_shape, execute_script, get_document_graph, get_screenshot, get_sketch_diagnostics, inspect_object, list_documents, reload_handlers, and tracked_recompute. This uniformity makes the set predictable and easy to navigate for an agent.
With 9 tools, the server is well-scoped for FreeCAD modeling and diagnostics, covering essential operations like analysis, inspection, scripting, and recomputation. Each tool serves a unique function, and the count is neither too sparse nor bloated, fitting typical MCP server ranges of 3-15 tools effectively.
The tool set provides comprehensive coverage for inspecting, analyzing, and managing FreeCAD models, including diagnostics, scripting, and document handling. However, there are minor gaps in direct creation or modification tools (e.g., no create_sketch or modify_object), though execute_script can serve as a workaround for such operations.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Agent-first CAD: editable .kcad.ts source, deterministic review, OpenCASCADE kernel.
Live browser debugging for AI assistants — DOM, console, network via MCP.
DXF and PDF/X-4 for AI agents: structured facts, PNG renders, an interactive in-chat viewer.
Your Aurentia workspace — projects, CRM, tasks, deliverables — in Claude, Cursor or any MCP client.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/theosib/FreeCAD-MCP-Server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
