# jupytercad-mcp
An MCP server for [JupyterCAD](https://github.com/jupytercad/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.
## Usage
The 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:
```bash
uvx --with jupytercad-mcp jupytercad-mcp
```
To use the [`streamable-http`](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) transport, use this command instead:
```bash
uvx --with jupytercad-mcp jupytercad-mcp streamable-http
```
### Example
An 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:
1. Clone the repository and navigate into the directory:
```bash
git clone git@github.com:asmith26/jupytercad-mcp.git
cd jupytercad-mcp
```
2. Install the OpenAI Agents SDK. A Makefile target is provided for convenience:
```bash
make setup-examples-env
```
3. 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/)).
4. Run JupyterLab from the project's root directory:
```bash
make jupyter-lab
```
5. 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.
6. (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:
```bash
make mlflow-ui
```
7. Run the example with the default instruction, "Add a box with width/height/depth 1":
```bash
make example-openai-agents-client
```
#### Interactive Chat Interface
The example includes an interactive chat interface using the OpenAI Agents SDK's
[REPL utility](https://openai.github.io/openai-agents-python/repl/). To enable it, set [`USE_REPL=True`](examples/openai_agents_client.py#L14).
#### `streamable-http`
To use the `streamable-http` transport, first start the MCP server:
```bash
uvx --with jupytercad-mcp jupytercad-mcp streamable-http
```
Then, run the example with the `TRANSPORT` variable set to `"streamable-http"` in the [client example](examples/openai_agents_client.py#L12).
## Tools
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "jupytercad-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "jupytercad, jupyterlab, mcp, computer-aided design, cad",
"author": "asmith26",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/93/6d/8a4b7c85a7873b41b6b8c37da0eb858cee359784878a27e1e039d5a8e0a6/jupytercad_mcp-0.1.1.tar.gz",
"platform": null,
"description": "# jupytercad-mcp\n\nAn MCP server for [JupyterCAD](https://github.com/jupytercad/JupyterCAD) that allows you to control it using LLMs/natural language.\n\nhttps://github.com/user-attachments/assets/7edb31b2-2c80-4096-9d9c-048ae27c54e7\n\nSuggestions and contributions are very welcome.\n\n## Usage\n\nThe 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:\n\n```bash\nuvx --with jupytercad-mcp jupytercad-mcp\n```\n\nTo use the [`streamable-http`](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) transport, use this command instead:\n\n```bash\nuvx --with jupytercad-mcp jupytercad-mcp streamable-http\n```\n\n### Example\n\nAn 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:\n\n1. Clone the repository and navigate into the directory:\n ```bash\n git clone git@github.com:asmith26/jupytercad-mcp.git\n cd jupytercad-mcp\n ```\n\n2. Install the OpenAI Agents SDK. A Makefile target is provided for convenience:\n ```bash\n make setup-examples-env\n ```\n\n3. 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/)).\n\n4. Run JupyterLab from the project's root directory:\n ```bash\n make jupyter-lab\n ```\n\n5. 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.\n\n6. (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:\n ```bash\n make mlflow-ui\n ```\n\n7. Run the example with the default instruction, \"Add a box with width/height/depth 1\":\n ```bash\n make example-openai-agents-client\n ```\n\n#### Interactive Chat Interface\n\nThe example includes an interactive chat interface using the OpenAI Agents SDK's \n[REPL utility](https://openai.github.io/openai-agents-python/repl/). To enable it, set [`USE_REPL=True`](examples/openai_agents_client.py#L14).\n\n#### `streamable-http`\n\nTo use the `streamable-http` transport, first start the MCP server:\n```bash\nuvx --with jupytercad-mcp jupytercad-mcp streamable-http\n```\n\nThen, run the example with the `TRANSPORT` variable set to `\"streamable-http\"` in the [client example](examples/openai_agents_client.py#L12).\n\n## Tools\n\nThe following tools are available:\n\n- **get_current_cad_design**: Reads the current content of the JCAD document.\n- **remove**: Remove an object from the document.\n- **rename**: Rename an object in the document.\n- **add_annotation**: Add an annotation to the document.\n- **remove_annotation**: Remove an annotation from the document.\n- **add_occ_shape**: Add an OpenCascade TopoDS shape to the document.\n- **add_box**: Add a box to the document.\n- **add_cone**: Add a cone to the document.\n- **add_cylinder**: Add a cylinder to the document.\n- **add_sphere**: Add a sphere to the document.\n- **add_torus**: Add a torus to the document.\n- **cut**: Apply a cut boolean operation between two objects.\n- **fuse**: Apply a union boolean operation between two objects.\n- **intersect**: Apply an intersection boolean operation between two objects.\n- **chamfer**: Apply a chamfer operation on an object.\n- **fillet**: Apply a fillet operation on an object.\n- **set_visible**: Sets the visibility of an object.\n- **set_color**: Sets the color of an object.\n",
"bugtrack_url": null,
"license": null,
"summary": "An MCP server for JupyterCAD that allows you to control it using natural language.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/asmith26/jupytercad-mcp"
},
"split_keywords": [
"jupytercad",
" jupyterlab",
" mcp",
" computer-aided design",
" cad"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c6ba1bad306a905f88b0558c95a67725d99d13cfe2571f381e35d1abf451af3f",
"md5": "7bd5c1b9f299e2649ef0fd08014d5c8b",
"sha256": "349b49b22ce691c0dedff2a1cfee9ef9af62a7071f59d0e27e812dbe62a2ba79"
},
"downloads": -1,
"filename": "jupytercad_mcp-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7bd5c1b9f299e2649ef0fd08014d5c8b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 4621,
"upload_time": "2025-10-07T21:34:56",
"upload_time_iso_8601": "2025-10-07T21:34:56.936201Z",
"url": "https://files.pythonhosted.org/packages/c6/ba/1bad306a905f88b0558c95a67725d99d13cfe2571f381e35d1abf451af3f/jupytercad_mcp-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "936d8a4b7c85a7873b41b6b8c37da0eb858cee359784878a27e1e039d5a8e0a6",
"md5": "cdb9022be72614789f910d9c12b3123d",
"sha256": "4f58f15d04b0ca15cfb88c965fbed97f743583790829122790587e3d63df6d15"
},
"downloads": -1,
"filename": "jupytercad_mcp-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "cdb9022be72614789f910d9c12b3123d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 3606,
"upload_time": "2025-10-07T21:34:58",
"upload_time_iso_8601": "2025-10-07T21:34:58.267930Z",
"url": "https://files.pythonhosted.org/packages/93/6d/8a4b7c85a7873b41b6b8c37da0eb858cee359784878a27e1e039d5a8e0a6/jupytercad_mcp-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-07 21:34:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "asmith26",
"github_project": "jupytercad-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jupytercad-mcp"
}
JSON
