CADCraft MCP: A Practical Guide to AI-Assisted CAD

01 / DEFINITION

What is CADCraft MCP?

CADCraft MCP is a local MCP server that ships inside CADCraft’s command-line tool. It is not a separate download, a hosted service or a cloud API — it is the same cadcraft-cli binary you would use to convert a file, started in a mode that speaks the Model Context Protocol.

That matters because MCP is the protocol AI agents use to discover and call another program’s tools. By implementing it, CADCraft exposes its CAD operations — typing commands at the prompt, querying entities, rendering a preview, saving a drawing — as callable tools. An MCP-capable agent such as Claude Code, Claude Desktop, Cursor or any other MCP client can then work the drawing on your behalf.

The practical result: you describe the part in words, and the agent turns that into CAD commands, checks what it actually drew, renders a picture you can look at, and writes the file. The official MCP guide documents client configuration, tool arguments and an example session; docs/control-protocol.md documents the JSON channel the desktop app exposes alongside it.

The MCP tools it exposes

The official MCP guide and tool schemas describe the following operations. Interface tools require a connection to the desktop app; drawing and file operations are also available headless.

Use your client’s discovered MCP tool schemas for the installed server. Within that session, list_commands returns the CAD command catalog; it is distinct from the MCP tool list. Parameter definitions are linked in the official tool source.

02 / CLIENT SETUP

Connecting an MCP client

Obtain the CLI for your system from the official downloads or follow the repository’s build instructions. Use documentation that matches your installed release.

There are two ways to run the server, and they expose different tool sets. Headless is the simpler and the one most automation should start with; bridging to the app is for when you want the agent working in front of you.

Headless: the minimal setup

cadcraft-cli mcp

That single invocation starts an MCP server on stdio. An MCP client that launches stdio servers needs two things from its configuration: the executable to run, and the arguments to pass. For CADCraft those are cadcraft-cli and mcp.

The official MCP guide provides this configuration example for Claude Code / Claude Desktop. Other clients may use different configuration keys and file locations; follow their own MCP setup documentation rather than assuming this JSON works everywhere.

{
  "mcpServers": {
    "cadcraft": {
      "command": "cadcraft-cli",
      "args": ["mcp"]
    }
  }
}

If cadcraft-cli is not on your PATH, point command at the full path of the binary you downloaded instead.

Bridged: driving a live desktop session

To let the agent see and click the application, start the desktop build with the control port open, then connect the CLI to that address:

# Terminal 1: launch the desktop app with its control channel
cadcraft --control 7979

# Terminal 2: attach the MCP server to that session
cadcraft-cli mcp --connect 127.0.0.1:7979

This is the invocation documented in docs/mcp.md. Use the executable paths from your installation if the binaries are not on PATH. Keep the drawing you want to edit active in the desktop session.

In this mode screenshot, ui_inspect and ui_click are available. Without a deferred connection option, startup fails if the app is unreachable. A missing --connect address is an error; it does not silently fall back to a separate headless drawing.

When the client starts before the app

The checked docs describe --lazy to defer connecting until the first tool call, and --launch to open the desktop app on macOS when a tool call finds it unavailable. Calls fail with a message until the app answers. The official macOS launch configuration is:

{
  "mcpServers": {
    "cadcraft": {
      "command": "cadcraft-cli",
      "args": ["mcp", "--connect", "127.0.0.1:7979", "--launch"]
    }
  }
}

These options come from the repository snapshot linked above. Check support in your installed release before adding them.

cadcraft-cli run --sample --script 'CIRCLE 22,3 1
' \
  --save out.dxf --export out.png

cadcraft-cli info drawing.dxf
cadcraft-cli convert drawing.dxf drawing.svg
cadcraft-cli commands    # list the commands this build supports

03 / THE LOOP

Draw, inspect, render, save

Keep the drawing in one MCP session: create geometry, read it back, render it for review, then save that same drawing. A separate CLI process has its own session and will not save the agent’s current drawing automatically.

Step 3 is the one people skip. inspect_drawing and query_entities let the agent read the drawing back and compare it against the requirement. A command that returned without error is not proof that the geometry landed where you meant it to.

Editing an existing DXF

Open a working copy, query its entities and use the returned handles when editing. The official tool definitions document move with handles and delta. The sample handle 10A below comes from that source; replace it with the intended entity’s actual handle from your query before making the call.

open {"path":"/absolute/path/input-copy.dxf"}
query_entities {"type":"Circle","limit":10}
list_commands {"filter":"move"}
execute {"command":"move","params":{"handles":["10A"],"delta":[5,0]}}
inspect_drawing {"entities":true,"limit":100}
render {"fit":true}
save {"path":"/absolute/path/edited-copy.dxf"}

This is a documented edit pattern, not an executed test. Review the geometry and reopen the saved copy in the target application before replacing an original drawing.

What CADCraft can read and write

Whatever the agent produces has to leave in a format you can actually use. The product page states a broad DXF range; the repository’s format guide records detailed limits that vary by version. Check both the release and the target file format.

Opening a drawing is not evidence that saving preserves it. Some entities and custom data may be lost or changed. The checked snapshot documents raw preservation of some unknown DXF records, while DWG conversion drops additional data. The format guide records these limits; the older v0.5.0 guide has different restrictions. Test your own files in your target application before relying on round-trip compatibility.

04 / WORKED EXAMPLE

A 2D part, from request to saved DXF

The requirement

Create a simple rectangular mounting plate, 100 × 60 mm, with square corners and four Ø6 mm holes. Hole centres are (10, 10), (90, 10), (10, 50) and (90, 50). Use a metric drawing with OUTLINE and HOLES layers. Include a dimension for the 100 mm width, render for review and save DXF.

What the agent does with it

Start a new headless session for the example. In a bridged session,new_drawing changes the active desktop drawing, so save your current work first. The agent should discover the command parameters with list_commands, then set up the metric drawing and outline layer:

list_commands {"filter":"layer.new"}
list_commands {"filter":"circle"}
new_drawing {"metric":true}
execute {"command":"layer.new","params":{"name":"OUTLINE","color":"red","current":true}}
command_line {"text":"rectang 0,0 100,60"}
command_line {"text":"dimlinear 0,0 100,0 50,-8"}

Create the current hole layer, then use the documented structured circle command with a radius of 3 drawing units at each requested centre. The layer command schema and circle parameters are from the official tool definitions; the dimensions and coordinates are adapted for this part.

execute {"command":"layer.new","params":{"name":"HOLES","color":"red","current":true}}
execute {"command":"circle","params":{"center":[10,10],"radius":3}}
execute {"command":"circle","params":{"center":[90,10],"radius":3}}
execute {"command":"circle","params":{"center":[10,50],"radius":3}}
execute {"command":"circle","params":{"center":[90,50],"radius":3}}

Here 1 drawing unit is intended to represent 1 mm. Verify units in the drawing data and downstream CAD application rather than treating a metric template alone as proof of the required scale. The example uses square corners; it does not demonstrate fillets, machining tolerances or manufacturing readiness.

Read the drawing back. Check the outline spans 100 × 60 units, the width dimension exists, both layers are present, and the hole query returns four circles at the requested centres with radius 3. These are expected checks, not observed results:

inspect_drawing {"entities":true,"limit":100}
query_entities {"type":"Circle","layer":"HOLES","limit":10}
query_entities {"layer":"OUTLINE","limit":20}

With the geometry confirmed, the agent renders a preview for human approval and then saves. render is the documented MCP tool that returns a PNG:

render {"width":1200,"height":800,"fit":true}

After review, use the documented save tool in the same session. Replace the example paths with absolute, writable paths on the machine running the server. Saving PNG exports a preview; saving DXF writes the editable drawing.

save {"path":"/absolute/path/plate.dxf"}
save {"path":"/absolute/path/plate.png"}
open {"path":"/absolute/path/plate.dxf"}
inspect_drawing {"entities":true,"limit":100}
query_entities {"type":"Circle","layer":"HOLES","limit":10}

Compare the reopened drawing with the checks above, then open the DXF in your target workflow and verify units, dimensions, layers and geometry. Record the CADCraft version, DXF output version and test date before treating this as a repeatable process.

Handle errors before continuing

Official docs specify JSON-RPC -32602 for invalid tool parameters and isError: true for a tool that runs and fails. Stop on either, inspect the current drawing and correct the cause before retrying. A successful tool response still needs geometry checks and human review.

No CADCraft output from this example is available because we have not run it. It does not establish that dimensions or layers survive saving, or that another CAD application reads the result correctly. The optional fixture below is a separate input for testing file fidelity, not the output of this mounting-plate example.

The fixture is an original DXF 2018 file with an outline, text, a rendered dimension, five named layers, a block reference and an ANSI31 hatch. It was prepared independently with ezdxf and released under CC0-1.0 — no customer drawings or third-party artwork. It is useful for checking whether your CADCraft build opens, edits and saves a known drawing. Preparing it is not a CADCraft test, and no round-trip result is claimed.

05 / BROWSER INTEGRATION

How AI 2D generation connects to CADCraft

The browser integration is live. CAD DESIGN X turns a prompt into bounded structured geometry, validates it, exports an R12 DXF, and passes that file to the embedded CADCraft editor through its same-origin host bridge.

This path does not use CADCraft MCP. The generated DXF opens automatically in the web editor, where you can inspect and modify entities and use CADCraft Save to download the edited file.

Always inspect dimensions and reopen exported DXF files in the downstream application used for production. The remaining questions below concern deeper MCP and file-fidelity validation, not the browser handoff.

06 / BEFORE WE CLAIM ANYTHING

What has to be verified first

The planned connection needs evidence for each of these questions before we can publish a reproducible integration tutorial.

1. Does your generation service expose an API?

   Confirm whether a callable endpoint is available, what authentication it needs and whether it returns an image, geometry or a file. The existing browser generator does not establish an MCP-ready API contract.

2. Can its output enter a file workflow CADCraft supports?

   A concept image is not editable DXF geometry. Determine whether the generation service can return geometry or whether a conversion step is needed, then verify the resulting format in the installed CADCraft build.

3. Are dimensions and layer structure preserved?

   Geometry alone is not a drawing. Units, layer names, dimension objects and block references must survive the handover, or downstream editing inherits the loss.

4. What happens when a step fails?

   Official MCP docs distinguish invalid parameters from tool failures reported with isError: true. The integration must handle both, inspect partial results and define when to retry or roll back.

5. Which CADCraft build and version was validated?

   A result is only meaningful against a recorded version. ArtCraft labels CADCraft “In development,” so an untested release note is not evidence.

Until each of these has a recorded answer tied to a CADCraft version and date, the CAD DESIGN X connection stays a plan. Once they do, this page graduates into a real integration tutorial with verified commands and configuration.

07 / FAQ & EVIDENCE

CADCraft MCP FAQ

Answers follow the official MCP guide, the control-protocol document and ArtCraft’s product page, checked October 14, 2026. They describe documented behavior, not results we measured ourselves.