CAiD MCP Server
Validated 3D CAD modeling for AI agents via CAiD + CadQuery. 54 tools with geometry validation.
Ask AI about CAiD MCP Server
Powered by Claude Β· Grounded in docs
I know everything about CAiD MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
CAiD MCP Server
An MCP server that gives AI agents validated 3D CAD modeling via CAiD and OCP (OpenCASCADE). No GUI needed β the modeling engine IS the server.
Every geometry operation is validated through CAiD's ForgeResult system, which tracks volume, surface area, and diagnostics. If a boolean silently fails (common with OCCT), the validation layer catches it and tells you why.
You: "Make a box with rounded edges and a hole through the top, show me a preview"
Claude β create_box β fillet_solid_edges β add_hole β preview_object β export_stl
Result: SVG preview + ~/cadquery-output/my_part.stl
Available Tools (54 across 13 categories)
Use discover_tools() to browse, or discover_tools(category="query") for a specific category.
| Category | Count | What it does |
|---|---|---|
| primitives | 7 | Box, cylinder, sphere, cone, torus, extruded polygon, revolved profile |
| modify | 4 | Holes, fillets, chamfers, shell β with index-based edge/face selection |
| transforms | 4 | Translate, rotate, scale, mirror |
| booleans | 4 | Union, cut, intersect, multi-combine |
| query | 6 | List edges/faces, measure objects/distances, find nearest edges/faces |
| view | 2 | Section cuts, exploded assembly views |
| scene | 5 | List, info, delete, duplicate, clear |
| export | 5 | SVG preview, STL, STEP, batch STL |
| heal | 3 | Validity checking, shape repair, face simplification |
| io | 3 | BREP export, STEP/BREP import |
| assembly | 5 | Create, add parts, move, rotate, merge |
| compound | 3 | Belt wires, curve arrays, pulley assemblies |
| advanced | 3 | CAiD scripting, linear patterns, tool discovery |
Project Structure
caid-mcp/
βββ server.py # Entry point
βββ caid_mcp/
β βββ __init__.py
β βββ core.py # Scene state, shared utilities
β βββ types.py # Pydantic result models (v0.6.0+)
β βββ tools/
β βββ primitives.py # Shape creation (7 tools)
β βββ modify.py # Holes, fillets, chamfers, shell (4 tools)
β βββ transforms.py # Translate, rotate, scale, mirror (4 tools)
β βββ booleans.py # Union, cut, intersect, combine (4 tools)
β βββ query.py # Geometry inspection and measurement (6 tools)
β βββ view.py # Section and exploded views (2 tools)
β βββ scene.py # Workspace management (5 tools)
β βββ export.py # STL, STEP, SVG preview (5 tools)
β βββ heal.py # Validation and repair (3 tools)
β βββ io.py # BREP/STEP import-export (3 tools)
β βββ assembly.py # Multi-part assemblies (5 tools)
β βββ compound.py # Belt/pulley systems (3 tools)
β βββ advanced.py # Scripting, patterns, tool router (3 tools)
βββ examples/
β βββ quickstart.py # Install verification script
β βββ GALLERY.md # Example gallery with prompts
β βββ images/ # Rendered example images
βββ tests/
β βββ test_cadquery_mcp.py
βββ pyproject.toml
βββ LLM_GUIDE.md # LLM-specific usage guide
βββ CHANGELOG.md
βββ LICENSE
Setup
Prerequisites
- Python 3.11+
Install
# 1. Create a virtual environment
python -m venv .venv
source .venv/bin/activate # macOS/Linux
# .venv\Scripts\activate # Windows
# 2. Install CAiD (brings in OCP and all dependencies)
pip install caid
# 3. Clone and install this server
git clone https://github.com/dreliq9/caid-mcp.git
cd caid-mcp
pip install -e ".[dev]"
Verify
source .venv/bin/activate
python -c "import caid; import mcp; print('All dependencies OK')"
pytest tests/ -v
Connect to Claude Code
claude mcp add-json caid '{"type":"stdio","command":"/FULL/PATH/TO/.venv/bin/python","args":["/FULL/PATH/TO/caid-mcp/server.py"]}' --scope user
Replace /FULL/PATH/TO/ with the actual absolute paths to your venv Python and the server.py file.
Or edit ~/.claude.json directly:
{
"mcpServers": {
"caid": {
"type": "stdio",
"command": "/FULL/PATH/TO/.venv/bin/python",
"args": ["/FULL/PATH/TO/caid-mcp/server.py"]
}
}
}
Claude Desktop
Add the same config to your Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Verify connection
claude mcp list # from terminal
/mcp # inside Claude Code
Key Features
Structured tool outputs (v0.6.0+)
Tools in primitives and query return Pydantic models. Each response carries
both a human-readable text block (via __str__) and a typed structuredContent
JSON payload. Agents can read fields like result.volume_mm3 or
result.bounding_box.xlen directly β no more regex on "OK Created..." strings.
create_box("lid", 50, 30, 5)
text: "OK Created box 'lid' | volume=7500.0mm3 | bbox=50.00x30.00x5.00mm"
structured: {ok: true, name: "lid", kind: "box", volume_mm3: 7500.0, bbox: {...}}
Old clients that only read text still work β this is additive, not a wire change.
Geometry Query and Measurement
The query tools let the LLM inspect what it built before modifying it β solving the "blind fillet" problem where the LLM guesses which edge to target.
list_edges("box") β every edge with index, endpoints, length, type
list_faces("box") β every face with index, area, center, normal
find_edges_near_point(...) β "what edges are near (10, 5, 2.5)?"
measure_distance(a, b) β min distance between two objects
Index-Based Edge/Face Selection
Instead of guessing selector strings like ">Z", the LLM can now:
- Call
list_edgesto see all edges with their indices - Call
fillet_solid_edges(name, radius, edge_indices="[2, 5, 8]")to target exactly those edges
Same for add_hole(face_index=3) and shell_object(face_index=0).
Section and Exploded Views
section_view("part", axis="X", offset=5.0) β cut and preview cross-section
exploded_view("assembly", scale=2.5) β push parts outward for inspection
Validated Operations
Every CAiD operation returns a ForgeResult with volume tracking. If a boolean union doesn't increase volume, you get a warning with a hint (shapes may not overlap). Silent OCCT failures are caught automatically.
CAiD Scripting Escape Hatch
When built-in tools can't do the job, run_cadquery_script (name kept for API compatibility) gives full access to CAiD and OCP:
script = """
from caid.vector import Vector
from OCP.BRepPrimAPI import BRepPrimAPI_MakeBox
from OCP.gp import gp_Pnt
# Use CAiD helpers or raw OCP calls
result = caid.make_box(20, 20, 10)
"""
Security note:
run_cadquery_scriptexecutes arbitrary Python in a subprocess with no sandboxing. The subprocess has full filesystem and network access. This is safe when the MCP server is used locally with trusted clients (e.g., Claude Code on your own machine). Do not expose this server to untrusted users without adding sandboxing β see Planned Fixes below.
Output Files
All exports go to ~/cadquery-output/ by default (directory name kept for backward compatibility). Override with:
export CAID_OUTPUT_DIR=/your/path
Or in the MCP config:
{
"env": { "CAID_OUTPUT_DIR": "/your/stl/folder" }
}
Examples
Real parts built through CAiD MCP tools. Each example highlights validated geometry, query-before-modify, and section views β things other CAD-for-AI tools can't do. See the full gallery for tool sequences and workflow breakdowns.
![]() Raspberry Pi Case Shell, port cutouts, section view verification | ![]() Headphone Stand Primitives, booleans, overlap validation |
![]() Hex Bolt & Nut Extruded polygon, chamfers, multi-part scene | ![]() Cable Clip Boolean subtract, snap-fit slot, 30-second build |
Sample Prompts
- "Design a Pi case with port cutouts, then section it to verify wall thickness"
- "Make a headphone stand β measure the total height when you're done"
- "Model an M10 bolt and nut, chamfer the edges, place them side by side"
- "List the edges on this part, then fillet just the inner joint by index"
- "Section view through the middle to check the internal hole dimensions"
Architecture
Claude Code / Claude Desktop / any MCP client
β
β stdio (JSON-RPC)
βΌ
MCP Server (server.py)
β
βββ tools/primitives β create shapes
βββ tools/modify β holes, fillets, chamfers, shell
βββ tools/transforms β move, rotate, scale, mirror
βββ tools/booleans β union, cut, intersect
βββ tools/query β geometry inspection and measurement
βββ tools/view β section cuts, exploded views
βββ tools/scene β workspace management
βββ tools/export β STL, STEP, SVG preview
βββ tools/heal β validation, repair, simplification
βββ tools/io β BREP/STEP import-export
βββ tools/assembly β multi-part assemblies
βββ tools/compound β belt/pulley systems
βββ tools/advanced β scripting, patterns, tool router
β
βΌ
CAiD β OCP (OpenCASCADE) kernel
β
βΌ
STL / STEP / BREP / SVG files
Troubleshooting
"CAiD is not installed" β Make sure you installed CAiD in the same venv: pip install caid
"OCP is not installed" β OCP is installed automatically as a dependency of CAiD. If missing: pip install OCP
Claude Code doesn't show tools β claude mcp list to check registration. Make sure the path to your venv's Python binary is absolute. Restart Claude Code.
SVG preview is blank β Object might have zero volume. Use list_objects to check dimensions.
Fillet/chamfer fails β Try heal_object first, then retry with a smaller radius. Use list_edges to verify the shortest edge length.
Tests failing β Make sure you're in the venv: source .venv/bin/activate && pytest tests/ -v
Planned Fixes
- Sandbox
run_cadquery_scriptβ The scripting escape hatch currently runs arbitrary Python with no restrictions. Planned: restricted imports whitelist, filesystem jailing toOUTPUT_DIR, network access disabled. Until then, only use with trusted MCP clients. - Windows path handling β Fixed in v0.4.1. Subprocess scripts previously used f-string path interpolation that broke on Windows backslashes.
Acknowledgments
CAiD MCP was co-developed by Adam Steen and Claude (Anthropic).
License
MIT β see LICENSE.




