Content
# CAD-MCP Server (CAD Model Context Protocol Server)
[English](/README_en.md) | [中文](/README_zh.md)
> **Public GitHub version: v1.1.0**
>
> The public GitHub materials are maintained as the v1.1.0 baseline. The server configuration in `src/config.json` also reports `"version": "1.1.0"`.
## Project Introduction
CAD-MCP is an innovative CAD control service that allows controlling CAD software for drawing operations through natural language instructions. This project combines natural language processing and CAD automation technology, enabling users to create and modify CAD drawings through simple text commands without manually operating the CAD interface.
## Features
### CAD Control Functions
- **Multiple CAD Software Support**: Supports mainstream CAD software including AutoCAD (with AutoCAD 2024 ProgID), GstarCAD (GCAD) and ZWCAD
- **Headless Backend (NEW)**: Supports `ezdxf` for offline DXF generation without AutoCAD installed.
- **Undo/Redo (NEW)**: Full support for undoing and redoing operations via the tool API.
- **Consolidated Tools (NEW)**: Modernized API with high-level `drawing`, `entity`, `layer`, and `system` tools.
- **Basic Drawing Functions**:
- Line drawing
- Circle drawing
- Arc drawing
- Rectangle drawing
- Polyline drawing
- Text addition
- Pattern filling
- Dimension annotation
- **Layer Management**: Create and switch layers
- **Drawing Save**: Save the current drawing as a DWG file
- **Command Line Execution**: Execute CAD commands/aliases directly via MCP (supports `sample/11.txt` aliases)
- **Active Document Workflow**: Inspect and edit the drawing currently open in CAD with handle-based tools such as `get_active_document_info`, `list_text_entities`, `update_entity`, `batch_update_entities`, `update_level_texts`, `save_as_generated`, and `open_local_drawing`.
## ChatGPT Upload Limitation
ChatGPT web uploads are stored inside OpenAI's sandbox. Paths such as `/mnt/data/plan.dwg` or `/mnt/data/plan.dxf` are not Windows paths and cannot be read by this local CAD MCP server.
Do not rely on this pattern:
```json
{ "file_path": "/mnt/data/plan.dwg" }
```
The server intentionally rejects `/mnt/data/...` and `file_id` inputs unless an external bridge sends the actual file bytes. It also does not search `workspace`, `inbox`, or `Downloads` by same filename for sandbox paths, because that can open an old cached drawing with the same name.
Supported safe paths are:
- Open the original drawing in CAD and use active-document tools (`get_active_document_info`, `list_text_entities`, `update_entity`, `save_as_generated`).
- Send actual file bytes with `upload_and_open_drawing(file_base64=...)`.
- Send large files with `upload_drawing_chunk`.
- Pass an explicit local Windows path.
- Pass `inbox_name` only for a file that was deliberately placed in `C:\cad-mcp\inbox`.
DWG to DXF conversion is supported only after the server has real bytes or a real local file path. A ChatGPT sandbox path by itself is not enough.
### Natural Language Processing Functions
- **Command Parsing**: Parse natural language instructions into CAD operation parameters
- **Color Recognition**: Extract color information from text and apply it to drawing objects
- **Shape Keyword Mapping**: Support recognition of various shape description words
- **Action Keyword Mapping**: Recognize various drawing and editing actions
## Demo
The following is the demo video.
## Installation Requirements
### Dependencies
```
pywin32>=228 # Windows COM interface support
mcp>=0.1.0 # Model Control Protocol library
pydantic>=2.0.0 # Data validation
typing>=3.7.4.3 # Type annotation support
```
### System Requirements
- Windows operating system
- Installed CAD software (AutoCAD, GstarCAD, or ZWCAD)
## Configuration
The configuration file is located at `src/config.json` and contains the following main settings:
```json
{
"server": {
"name": "CAD MCP Server",
"version": "1.1.0"
},
"cad": {
"type": "AutoCAD2024",
"prog_id": "AutoCAD.Application.24.3",
"command_alias_file": "../sample/11.txt",
"startup_wait_time": 20,
"command_delay": 0.5
},
"output": {
"directory": "./output",
"default_filename": "cad_drawing.dwg"
}
}
```
- **server**: Server name and version information
- **cad**:
- `type`: CAD software type (AutoCAD, AutoCAD2024, GCAD, GstarCAD, or ZWCAD)
- `prog_id`: Optional COM ProgID override/target (e.g., `AutoCAD.Application.24.3`)
- `command_alias_file`: Optional alias file path for command execution (default: `../sample/11.txt`)
- `startup_wait_time`: CAD startup waiting time (seconds)
- `command_delay`: Command execution delay (seconds)
- **output**: Output file settings
## Usage
### Starting the Service
```
python src/server.py
```
### Claude Desktop & Windsurf
```bash
# add to claude_desktop_config.json. Note: use your path
{
"mcpServers": {
"CAD": {
"command": "python",
"args": [
# your path, e.g.: "C:\\cad-mcp\\src\\server.py"
"~/server.py"
]
}
}
}
```
### Cursor
```bash
# Add according to the following diagram Cursor MCP. Note: use your path
```
Note：The new version of cursor has also been changed to JSON configuration, please refer to the previous section
### MCP Inspector
```bash
# Note: use your path
npx -y @modelcontextprotocol/inspector python C:\\cad-mcp\\src\\server.py
```
### Service API
The server provides the following main API functions:
- `drawing`: General drawing operations (save, open, clear, undo, redo)
- `entity`: Draw geometric entities (line, circle, polyline, text)
- `layer`: Layer management (list, create, freeze, lock, etc.)
- `system`: System and backend status
- `draw_line`: Draw a line (Legacy)
- `draw_circle`: Draw a circle (Legacy)
- `draw_arc`: Draw an arc (Legacy)
- `draw_polyline`: Draw a polyline (Legacy)
- `draw_rectangle`: Draw a rectangle (Legacy)
- `draw_text`: Add text (Legacy)
- `draw_hatch`: Draw a hatch pattern (Legacy)
- `add_dimension`: Add linear dimension (Legacy)
- `save_drawing`: Save the drawing (Legacy)
- `execute_cad_command`: Execute CAD command aliases such as `L`, `C`, `PL` (from `sample/11.txt`)
- `process_command`: Process natural language commands
## Project Structure
```
CAD-MCP/
├── imgs/ # Images and video resources
│ └── CAD-mcp.mp4 # Demo video
├── requirements.txt # Project dependencies
└── src/ # Source code
├── __init__.py # Package initialization
├── cad_controller.py # CAD controller
├── config.json # Configuration file
├── nlp_processor.py # Natural language processor
└── server.py # Server implementation
```
## License
MIT License
