Jupytercad MCP

1# jupytercad-mcp
2 
3An MCP server for [JupyterCAD](https://github.com/jupytercad/JupyterCAD) that allows you to control it using LLMs/natural language.
4 
5https://github.com/user-attachments/assets/7edb31b2-2c80-4096-9d9c-048ae27c54e7
6 
7Suggestions and contributions are very welcome.
8 
9## Usage
10 
11The default transport mechanism is [`stdio`](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio). To start the server with `stdio`, use the following command:
12 
13```bash
14uvx --with jupytercad-mcp jupytercad-mcp
15```
16 
17To use the [`streamable-http`](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) transport, use this command instead:
18 
19```bash
20uvx --with jupytercad-mcp jupytercad-mcp streamable-http
21```
22 
23### Example
24 
25An example using the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python) is available at [examples/openai_agents_client.py](examples/openai_agents_client.py). To run it, follow these steps:
26 
271.  Clone the repository and navigate into the directory:
28    ```bash
29    git clone git@github.com:asmith26/jupytercad-mcp.git
30    cd jupytercad-mcp
31    ```
32 
332.  Install the OpenAI Agents SDK. A Makefile target is provided for convenience:
34    ```bash
35    make setup-examples-env
36    ```
37 
383.  In [examples/openai_agents_client.py](examples/openai_agents_client.py#L13), update line 13 to configure a `MODEL` (see [supported models](https://openai.github.io/openai-agents-python/models/)).
39 
404.  Run JupyterLab from the project's root directory:
41    ```bash
42    make jupyter-lab
43    ```
44 
455.  In JupyterLab, create a new "CAD file" and rename it to **my_cad_design.jcad**. This file path matches the default [`JCAD_PATH`](examples/openai_agents_client.py#L16) in the example, allowing you to visualise the changes made by the JupyterCAD MCP server.
46 
476.  (Optional) The OpenAI Agents SDK supports [tracing](https://openai.github.io/openai-agents-python/tracing/) to record events like LLM generations and tool calls. To enable it, set [`USE_MLFLOW_TRACING=True`](examples/openai_agents_client.py#L15) and run the MLflow UI:
48    ```bash
49    make mlflow-ui
50    ```
51 
527.  Run the example with the default instruction, "Add a box with width/height/depth 1":
53    ```bash
54    make example-openai-agents-client
55    ```
56 
57#### Interactive Chat Interface
58 
59The example includes an interactive chat interface using the OpenAI Agents SDK's 
60[REPL utility](https://openai.github.io/openai-agents-python/repl/). To enable it, set [`USE_REPL=True`](examples/openai_agents_client.py#L14).
61 
62#### `streamable-http`
63 
64To use the `streamable-http` transport, first start the MCP server:
65```bash
66uvx --with jupytercad-mcp jupytercad-mcp streamable-http
67```
68 
69Then, run the example with the `TRANSPORT` variable set to `"streamable-http"` in the [client example](examples/openai_agents_client.py#L12).
70 
71## Tools
72 
73The following tools are available:
74 
75- **get_current_cad_design**: Reads the current content of the JCAD document.
76- **remove**: Remove an object from the document.
77- **rename**: Rename an object in the document.
78- **add_annotation**: Add an annotation to the document.
79- **remove_annotation**: Remove an annotation from the document.
80- **add_occ_shape**: Add an OpenCascade TopoDS shape to the document.
81- **add_box**: Add a box to the document.
82- **add_cone**: Add a cone to the document.
83- **add_cylinder**: Add a cylinder to the document.
84- **add_sphere**: Add a sphere to the document.
85- **add_torus**: Add a torus to the document.
86- **cut**: Apply a cut boolean operation between two objects.
87- **fuse**: Apply a union boolean operation between two objects.
88- **intersect**: Apply an intersection boolean operation between two objects.
89- **chamfer**: Apply a chamfer operation on an object.
90- **fillet**: Apply a fillet operation on an object.
91- **set_visible**: Sets the visibility of an object.
92- **set_color**: Sets the color of an object.
93