jupytercad-mcp is an MCP (Model Context Protocol) server for JupyterCAD, designed to let users control JupyterCAD's CAD operations through an LLM or natural language. This project is open-sourced by asmith26 on GitHub, and suggestions and contributions are welcome.
[Purpose] The main purpose of this project is to connect JupyterCAD's modeling capabilities to LLM applications that support MCP, enabling AI to directly operate CAD documents with natural language instructions to complete tasks such as geometry creation, modification, and Boolean operations.
[Main Capabilities] The server provides a set of tools covering common CAD design operations:
- get_current_cad_design: Read the contents of the current 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_cone, add_cylinder, add_sphere, add_torus: Add a box, cone, cylinder, sphere, and torus respectively.
- cut, fuse, intersect: Perform cut, union, and intersection Boolean operations between two objects.
- chamfer, fillet: Perform chamfer and fillet operations on an object.
- set_visible: Set the visibility of an object.
- set_color: Set the color of an object.
[Usage] The default transport mechanism is stdio, and the server can be started with the corresponding command; if streamable-http transport is needed, use another command to start it. The project provides an example using the OpenAI Agents SDK in examples/openai_agents_client.py. The steps to run the example include:
- Clone the repository and enter the directory: git clone git@github.com:asmith26/jupytercad-mcp.git; cd jupytercad-mcp
- Install the OpenAI Agents SDK, you can use the provided Makefile target: make setup-examples-env
- Update line 13 in examples/openai_agents_client.py to configure MODEL (see supported models).
- Run JupyterLab from the project root directory: make jupyter-lab
- In 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, so that the modifications made by the JupyterCAD MCP server can be visualized.
- Run the example, with the default instruction "Add a box with width/height/depth 1": make example-openai-agents-client The example also includes an interactive chat interface for the REPL tool based on the OpenAI Agents SDK, which can be enabled by setting USE_REPL=True. To use streamable-http transport, first start the MCP server, then set the TRANSPORT variable to "streamable-http" in the client example and run the example. Optionally, the OpenAI Agents SDK supports tracing to record events such as LLM generations and tool calls, which can be enabled by setting USE_MLFLOW_TRACING=True and running the MLflow UI (make mlflow-ui).
[Applicable Scenarios] Suitable for users or developers who want to use an LLM for natural language-driven CAD modeling, geometry operations, and Boolean operations in the JupyterLab environment.
[Limitations] The materials do not clearly list detailed descriptions of specific limitations or usage prerequisites; some features (such as tracing and REPL) require additional configuration.
