Allows AI agents to control JupyterCAD, a 3D CAD modeling extension for JupyterLab, through natural language commands to create, modify, and manipulate 3D shapes and perform boolean operations.
Click on "Deploy 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., "@jupytercad-mcp Add a box with width 2, height 3, depth 4"
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 server for JupyterCAD that allows you to control it using LLMs/natural language.
https://github.com/user-attachments/assets/7edb31b2-2c80-4096-9d9c-048ae27c54e7
Suggestions and contributions are very welcome.
The default transport mechanism is stdio. To start the server with stdio, use the following command:
uvx --with jupytercad-mcp jupytercad-mcpTo use the streamable-http transport, use this command instead:
uvx --with jupytercad-mcp jupytercad-mcp streamable-httpAn example using the OpenAI Agents SDK is available at examples/openai_agents_client.py. To run it, follow these steps:
Clone the repository and navigate into the directory:
git clone git@github.com:asmith26/jupytercad-mcp.git
cd jupytercad-mcpInstall the OpenAI Agents SDK. A Makefile target is provided for convenience:
make setup-examples-envIn examples/openai_agents_client.py, update line 13 to configure a MODEL (see supported models).
Run JupyterLab from the project's root directory:
make jupyter-labIn JupyterLab, create a new "CAD file" and rename it to my_cad_design.jcad. This file path matches the default JCAD_PATH in the example, allowing you to visualise the changes made by the JupyterCAD MCP server.
(Optional) The OpenAI Agents SDK supports tracing to record events like LLM generations and tool calls. To enable it, set USE_MLFLOW_TRACING=True and run the MLflow UI:
make mlflow-uiRun the example with the default instruction, "Add a box with width/height/depth 1":
make example-openai-agents-clientThe example includes an interactive chat interface using the OpenAI Agents SDK's
REPL utility. To enable it, set USE_REPL=True.
streamable-httpTo use the streamable-http transport, first start the MCP server:
uvx --with jupytercad-mcp jupytercad-mcp streamable-httpThen, run the example with the TRANSPORT variable set to "streamable-http" in the client example.
Related MCP server: 3D MCP Server
The following tools are available:
get_current_cad_design: Reads the current content of the JCAD document.
remove: Remove an object from the document.
rename: Rename an object in the document.
add_annotation: Add an annotation to the document.
remove_annotation: Remove an annotation from the document.
add_occ_shape: Add an OpenCascade TopoDS shape to the document.
add_box: Add a box to the document.
add_cone: Add a cone to the document.
add_cylinder: Add a cylinder to the document.
add_sphere: Add a sphere to the document.
add_torus: Add a torus to the document.
cut: Apply a cut boolean operation between two objects.
fuse: Apply a union boolean operation between two objects.
intersect: Apply an intersection boolean operation between two objects.
chamfer: Apply a chamfer operation on an object.
fillet: Apply a fillet operation on an object.
set_visible: Sets the visibility of an object.
set_color: Sets the color of an object.
Add an annotation to the document.
:param parent: The object which holds the annotation. :param message: The first messages in the annotation. :param position: The position of the annotation. :param user: The user who create this annotation. :return: The id of the annotation if it is created.
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: parent (required), message (required), jcad_path (required), user, +1 more.
Add a box to the document.
:param name: The name that will be used for the object in the document. :param length: The length of the box. :param width: The width of the box. :param height: The height of the box. :param color: The color of the box in hex format (e.g., "#FF5733") or RGB float list. :param position: The shape 3D position. :param rotation_axis: The 3D axis used for the rotation. :param rotation_angle: The shape rotation angle, in degrees. :return: The document itself.
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: jcad_path (required), name, color, width, +5 more.
Add a cone to the document.
:param name: The name that will be used for the object in the document. :param radius1: The bottom radius of the cone. :param radius2: The top radius of the cone. :param height: The height of the cone. :param angle: The revolution angle of the cone (0: no cone, 180: half cone, 360: full cone). :param color: The color of the cone in hex format (e.g., "#FF5733") or RGB float list. :param position: The shape 3D position. :param rotation_axis: The 3D axis used for the rotation. :param rotation_angle: The shape rotation angle, in degrees. :return: The document itself.
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: jcad_path (required), name, angle, color, +6 more.
Add a cylinder to the document.
:param name: The name that will be used for the object in the document. :param radius: The radius of the cylinder. :param height: The height of the cylinder. :param angle: The revolution angle of the cylinder (0: no cylinder, 180: half cylinder, 360: full cylinder). :param color: The color of the cylinder in hex format (e.g., "#FF5733") or RGB float list. :param position: The shape 3D position. :param rotation_axis: The 3D axis used for the rotation. :param rotation_angle: The shape rotation angle, in degrees. :return: The document itself.
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: jcad_path (required), name, angle, color, +5 more.
Add an OpenCascade TopoDS shape to the document.
You need pythonocc-core installed in order to use this method.
:param shape: The Open Cascade shape to add. :param name: The name that will be used for the object in the document. :param position: The shape 3D position. :param rotation_axis: The 3D axis used for the rotation. :param rotation_angle: The shape rotation angle, in degrees. :return: The document itself.
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: shape (required), jcad_path (required), name, position, +2 more.
Add a sphere to the document.
:param name: The name that will be used for the object in the document. :param radius: The radius of the sphere. :param angle1: The revolution angle of the sphere on the X axis (0: no sphere, 180: half sphere, 360: full sphere). :param angle2: The revolution angle of the sphere on the Y axis (0: no sphere, 180: half sphere, 360: full sphere). :param angle3: The revolution angle of the sphere on the Z axis (0: no sphere, 180: half sphere, 360: full sphere). :param color: The color of the sphere in hex format (e.g., "#FF5733") or RGB float list. :param position: The shape 3D position. :param rotation_axis: The 3D axis used for the rotation. :param rotation_angle: The shape rotation angle, in degrees. :return: The document itself.
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: jcad_path (required), name, color, angle1, +6 more.
None
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: path (required), jcad_path (required), name, position, +2 more.
Add a torus to the document.
:param name: The name that will be used for the object in the document. :param radius1: The outer radius of the torus. :param radius2: The inner radius of the torus. :param angle1: The revolution angle of the torus on the X axis (0: no torus, 180: half torus, 360: full torus). :param angle2: The revolution angle of the torus on the Y axis (0: no torus, 180: half torus, 360: full torus). :param angle3: The revolution angle of the torus on the Z axis (0: no torus, 180: half torus, 360: full torus). :param color: The color of the torus in hex format (e.g., "#FF5733") or RGB float list. :param position: The shape 3D position. :param rotation_axis: The 3D axis used for the rotation. :param rotation_angle: The shape rotation angle, in degrees. :return: The document itself.
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: jcad_path (required), name, color, angle1, +7 more.
Apply a chamfer operation on an object. If no objects are provided as input, the last created object will be used as operand.
:param name: The name that will be used for the object in the document. :param shape: The input object used for the chamfer. Can be the name of the object or its index in the objects list. :param edge: The edge index where to apply chamfer. :param dist: The distance of the chamfer. :param color: The color in hex format (e.g., "#FF5733") or RGB float list. Defaults to the base object's color if None. :param position: The shape 3D position. :param rotation_axis: The 3D axis used for the rotation. :param rotation_angle: The shape rotation angle, in degrees. :return: The document itself.
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: jcad_path (required), dist, edge, name, +5 more.
Apply a cut boolean operation between two objects. If no objects are provided as input, the last two created objects will be used as operands.
:param name: The name that will be used for the object in the document. :param base: The base object that will be used for the cut. Can be the name of the object or its index in the objects list. :param tool: The tool object that will be used for the cut. Can be the name of the object or its index in the objects list. :param refine: Whether or not to refine the mesh during the cut computation. :param color: The color in hex format (e.g., "#FF5733") or RGB float list. Defaults to the base object's color if None. :param position: The shape 3D position. :param rotation_axis: The 3D axis used for the rotation. :param rotation_angle: The shape rotation angle, in degrees. :return: The document itself.
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: jcad_path (required), base, name, tool, +5 more.
Apply a fillet operation on an object. If no objects are provided as input, the last created object will be used as operand.
:param name: The name that will be used for the object in the document. :param shape: The input object used for the fillet. Can be the name of the object or its index in the objects list. :param edge: The edge index where to apply fillet. :param radius: The radius of the fillet. :param color: The color in hex format (e.g., "#FF5733") or RGB float list. Defaults to the base object's color if None. :param position: The shape 3D position. :param rotation_axis: The 3D axis used for the rotation. :param rotation_angle: The shape rotation angle, in degrees. :return: The document itself.
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: jcad_path (required), edge, name, color, +5 more.
Apply a union boolean operation between two objects. If no objects are provided as input, the last two created objects will be used as operands.
:param name: The name that will be used for the object in the document. :param shape1: The first object used for the union. Can be the name of the object or its index in the objects list. :param shape2: The first object used for the union. Can be the name of the object or its index in the objects list. :param refine: Whether or not to refine the mesh during the union computation. :param color: The color in hex format (e.g., "#FF5733") or RGB float list. Defaults to the base object's color if None. :param position: The shape 3D position. :param rotation_axis: The 3D axis used for the rotation. :param rotation_angle: The shape rotation angle, in degrees. :return: The document itself.
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: jcad_path (required), name, color, refine, +5 more.
Read the current content of a JCAD (JupyterCAD) document.
Use this tool to understand the current state of a JCAD file before modifying it.
:param jcad_path: The path to the JCAD file. :return: The current content of the JCAD file.
Inputs: jcad_path (required). Returns: result
Apply an intersection boolean operation between two objects. If no objects are provided as input, the last two created objects will be used as operands.
:param name: The name that will be used for the object in the document. :param shape1: The first object used for the intersection. Can be the name of the object or its index in the objects list. :param shape2: The first object used for the intersection. Can be the name of the object or its index in the objects list. :param refine: Whether or not to refine the mesh during the intersection computation. :param color: The color in hex format (e.g., "#FF5733") or RGB float list. Defaults to the base object's color if None. :param position: The shape 3D position. :param rotation_axis: The 3D axis used for the rotation. :param rotation_angle: The shape rotation angle, in degrees. :return: The document itself.
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: jcad_path (required), name, color, refine, +5 more.
Remove an object from the document.
:param name: The name of the object to remove. :return: The document itself.
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: name (required), jcad_path (required).
Remove an annotation from the document.
:param annotation_id: The id of the annotation
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: jcad_path (required), annotation_id (required).
Rename an object in the document.
:param old_name: The current name of the object. :param new_name: The new name for the object. :return: The document itself.
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: new_name (required), old_name (required), jcad_path (required).
Set the color of an object.
:param name: The name of the object. :param value: The color in hex format (e.g., "#FF5733").
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: name (required), value (required), jcad_path (required).
Set the visibility of an object.
:param name: The name of the object. :param value: The visibility value (True or False).
Warning: This tool will update the JCAD document at the given jcad_path.
To understand the current state of the document, you MUST first use the 'get_current_cad_design' tool.
Inputs: name (required), value (required), jcad_path (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 19 tools
Most tools have distinct purposes with clear verb_noun naming, but 'add_step_file' has no description and could be confused with 'add_occ_shape' since both import external geometry. The boolean and edge operations are clearly differentiated.
All tool names use lowercase snake_case and follow a predictable verb_noun pattern (add_*, set_*, remove_*) or single-word verbs (cut, fuse, intersect). Naming is consistent and easy to infer.
Nineteen tools is slightly above the typical well-scoped range, but each tool covers a necessary aspect of CAD manipulation (primitives, booleans, edge operations, annotations, properties). The count feels appropriate for the domain.
The set covers creation, boolean operations, chamfer/fillet, annotations, and basic properties, but lacks transformation tools (move/rotate existing objects) and export capabilities. Users can create shapes but cannot reposition them after creation, which is a significant gap.
CAD in ChatGPT and Claude: editable parts, STEP/STL/drawings, in-chat 3D, automatic checks.
Parametric 3D CAD for AI agents: build print-ready parts, check them, export STL, 3MF or STEP.
A browser 3D CAD for your AI: it scripts real-size models, uCAD builds them and returns pictures.
Design 3D-printable parts by chatting: create, edit, render and publish parametric forges.
