fcgen-mcp
An MCP server that lets LLMs safely generate parametric CAD parts through verified templates and FreeCAD.
LLM が検証済みテンプレートを通じて安全にパラメトリック CAD パーツを生成する MCP サーバー
!Python 3.10+ !License MIT !FreeCAD 0.19+
---
What is this?
Large Language Models can describe mechanical parts in natural language, but giving them unconstrained access to a CAD kernel is a recipe for broken geometry, invalid dimensions, and non-manufacturable output. fcgen-mcp solves this by placing a structured safety layer between the LLM and FreeCAD.
Instead of generating raw CAD scripts, the LLM selects from verified parametric templates, fills in parameters validated against JSON Schema and semantic rules, and receives deterministic STEP/STL output.
┌─────────────────────────────────┐
│ LLM (Claude, etc.) │
└────────────┬──────────────────────┘
│ MCP protocol
┌────────────▼──────────────────────┐
│ fcgen MCP Server │
│ ┌───────────┐ ┌──────────────┐ │
│ │ JSON │ │ Semantic │ │
│ │ Schema │ │ Validation │ │
│ └─────┬─────┘ └──────┬───────┘ │
│ └────────┬──────┘ │
│ ┌────────▼─────────┐ │
│ │ Template Registry │ │
│ │ (verified only) │ │
│ └────────┬─────────┘ │
└────────────────┼─────────────────┘
│ headless execution
┌────────────────▼─────────────────┐
│ FreeCAD (freecadcmd) │
│ → STEP / STL output │
└──────────────────────────────────┘Key Features
- 11 MCP tools -- complete workflow from discovery to generation, including assembly
- Template registry with candidate → verified lifecycle for quality control
- JSON Schema + semantic validation -- catches invalid geometry before it reaches FreeCAD
- Multi-part assembly with explicit placement (position + rotation)
- FreeCAD headless generation -- produces industry-standard STEP and STL files
- Deterministic artifact hashing -- identical parameters always produce identical output
Quick Start
Installation
pip install -e ".[mcp]"Launch the MCP server
python -m fcgen.mcp.serverClaude Desktop configuration
Add to your Claude Desktop claude_desktop_config.json:
{
"mcpServers": {
"fcgen": {
"command": "python",
"args": ["-m", "fcgen.mcp.server"]
}
}
}FreeCAD setup
If freecadcmd is not on your PATH, set the environment variable:
export FCGEN_FREECADCMD="/path/to/freecadcmd"Windows:
set FCGEN_FREECADCMD=C:\Program Files\FreeCAD 1.0\bin\freecadcmd.exeMCP Tools Reference
| Tool | Description | |------|-------------| | check_freecad | Verify FreeCAD is available and return version info | | list_templates | List all verified templates with purpose, tags, and parameter count | | get_template_schema | Return the full JSON Schema for a template | | get_template_example | Return example parameters for a template | | validate_params | Dry-run validation (schema + semantic) without generating output | | find_template | Search templates by purpose description, ranked by simplicity | | generate_part | Generate a single CAD part (STEP/STL) from a verified template | | generate_assembly | Generate a multi-part assembly with placement | | list_candidates | List unverified candidate templates | | propose_template | Register a new template as a candidate | | verify_template | Run verification checks and promote candidate to verified |
Usage Examples
Example 1: Discover and generate a bracket
A typical MCP tool call flow follows five steps -- discover, inspect, preview, validate, generate:
1. list_templates → see what's available
2. get_template_schema → inspect full parameter schema
3. get_template_example → get working sample parameters
4. validate_params → dry-run safety check
5. generate_part → produce STEP/STL filesStep 1 -- list_templates returns all verified templates:
{
"templates": {
"bracket": {
"purpose": "L-bracket with configurable holes",
"tags": ["structural", "mounting"],
"param_count": 10,
"top_level_keys": ["units", "material_hint", "bracket", "output"],
"has_example": true
},
"adapter_plate": {
"purpose": "Flat plate with two bolt circle patterns",
"tags": ["structural", "mounting", "plate"],
"param_count": 12,
"top_level_keys": ["units", "material_hint", "adapter_plate", "output"],
"has_example": true
}
}
}Step 3 -- get_template_example("bracket") returns ready-to-use parameters:
{
"units": "mm",
"material_hint": "al6061",
"bracket": {
"thickness": 3.0,
"leg_a": 40.0,
"leg_b": 60.0,
"width": 25.0,
"fillet": 1.0,
"chamfer": 0.5,
"holes": {
"pattern": "line",
"diameter": 5.5,
"count": 2,
"edge_offset": 8.0
}
},
"output": { "step": true, "stl": true, "tolerance": 0.1 }
}Step 4 -- validate_params("bracket", params) confirms validity before generation:
{ "valid": true }Step 5 -- generate_part("bracket", params) produces the CAD files:
{
"ok": true,
"result": {
"template": "bracket",
"artifact_hash": "77bd1e4cb686862707a2977db293aaed...",
"freecad_version": "1.0.0",
"outputs": {
"step": "output/bracket/model.step",
"stl": "output/bracket/model.stl",
"report_json": "output/bracket/report.json",
"report_md": "output/bracket/report.md"
}
}
}Example 2: Multi-part bolted assembly
The generate_assembly tool composes multiple parts with explicit placement. Here is a 7-part assembly: an adapter plate, two L-brackets, and four bolts.
{
"units": "mm",
"parts": [
{
"id": "base",
"template": "adapter_plate",
"params": { "...adapter_plate params..." },
"placement": { "position": [0, 0, 0], "rotation": [0, 0, 0] }
},
{
"id": "bracket_upper",
"template": "bracket",
"params": { "...bracket params..." },
"placement": { "position": [67.622, 17.417, 6.0], "rotation": [135, 0, 0] }
},
{
"id": "bracket_lower",
"template": "bracket",
"params": { "...bracket params..." },
"placement": { "position": [-67.622, -17.417, 6.0], "rotation": [-45, 0, 0] }
},
{
"id": "bolt_1",
"template": "bolt",
"params": { "...bolt params..." },
"placement": { "position": [53.126, 14.235, 9.0], "rotation": [0, 0, 0] }
}
],
"output": { "step": true, "stl": true }
}Each part is generated independently with full validation, then placed in a combined STEP/STL assembly. The remaining three bolts follow the same pattern at their respective positions.
Template Lifecycle
Templates go through a quality gate before they can be used for generation:
[Create files] → propose_template → candidate → verify_template → verified
│ │
▼ ▼
templates_candidate/ templates/- Candidate: template files exist and are registered, but not yet validated
- Verified: passed schema checks, test generation, and semantic validation -- available to
generate_part
LLMs can only generate parts from verified templates.
Available Templates
| Template | Description | Param Count | |----------|-------------|:-----------:| | bracket | L-bracket with configurable holes, fillet, and chamfer | 10 | | adapter_plate | Flat plate with two bolt circle patterns (PCD) | 12 | | enclosure | Rectangular box with lid and screw bosses | 10 | | bolt | Simple cylindrical bolt with head | 4 | | table_top | Flat table top plate with optional edge fillet | 4 | | simple_leg | Rectangular leg with chamfer and mounting hole | 5 |
Creating Custom Templates
Each template is a directory containing four files:
templates_candidate/my_part/
├── schema.json # JSON Schema defining all parameters
├── generator.py # Python logic: params → FreeCAD script args
├── freecad_generate.py # FreeCAD script: runs inside freecadcmd
└── examples/
└── basic.json # Working example parametersWorkflow:
- Create the template directory and files under
templates_candidate/ - Call
propose_template("my_part", purpose="...", tags=[...])to register it - Call
verify_template("my_part")to run automated checks - On success, the template is promoted to
templates/and becomes available for generation
FreeCAD Compatibility
| | Version | |---|---------| | Minimum | FreeCAD 0.19+ | | Recommended | FreeCAD 1.0 | | Tested | 0.21, 1.0 |
The project uses FreeCAD's Part module (primitives, booleans), Mesh module (STL export), and basic Placement API.
Project Structure
src/fcgen/
├── mcp/server.py # MCP tools (primary interface for LLMs)
├── core/runner.py # Generation engine
├── assembly/engine.py # Multi-part assembly with placement
├── validators/
│ ├── semantic.py # Dimensional & geometric validation
│ └── geometry.py # Geometry constraint checks
├── registry.py # Template lifecycle management
└── cli/main.py # CLI interface (secondary)
templates/ # Verified templates (ready for generation)
templates_candidate/ # Candidate templates (pending verification)
tests/ # Test suiteDocumentation
| Document | Description | |----------|-------------| | Quick Start | Build a desk in 5 minutes | | MCP Tools Reference | All 11 MCP tools with examples | | Template Guide | How to create custom templates | | Assembly Guide | Multi-part assembly creation |
Assembly Examples
Pre-built assembly examples in templates/assembly_examples/:
| File | Description | |------|-------------| | simple_desk.json | Standard 4-leg desk (1200 x 600 x 725mm) | | compact_desk.json | Compact desk for small rooms (800 x 500 x 700mm) | | standing_desk.json | Standing desk (1400 x 700 x 1050mm) | | desk_with_shelf.json | Desk with under-shelf storage | | plate_brackets_bolts.json | Bolted plate assembly with L-brackets | | plate_with_brackets.json | Plate with L-brackets |
Development
Install in development mode with MCP support:
pip install -e ".[mcp]"Run the test suite:
python -m pytest tests/ -vThere are currently 39 tests covering validation, generation, registry operations, and assembly logic.
License
MIT -- Copyright (c) 2026 kouya-group
