# AutoCAD MCP Server

A production-grade Model Context Protocol (MCP) server for AutoCAD on Windows, enabling AI assistants (Claude Desktop, ChatGPT, Cursor, etc.) to control AutoCAD through natural language.

## Features

- **10 Comprehensive MCP Tools** for CAD operations
- **AutoCAD COM API Integration** for native Windows automation
- **Natural Language Control** - "Draw a 100x50 rectangle" → creates geometry
- **Automatic Connection Management** with reconnection logic
- **Full Type Hints & Pydantic Validation** for safety
- **Production Logging** for debugging and monitoring
- **Unit Tests** covering all tools and edge cases
- **Fast & Lightweight** using FastMCP framework

## Tech Stack

- Python 3.11+
- [FastMCP](https://github.com/janus-ai/fastmcp) - MCP framework
- [pyautocad](https://pypi.org/project/pyautocad/) - AutoCAD COM wrapper
- [pywin32](https://github.com/pywin32) - Windows COM support
- [Pydantic](https://docs.pydantic.dev/) - Data validation
- [uv](https://github.com/astral-sh/uv) - Fast Python package manager

## Available Tools

### Drawing Tools

1. **create_line** - Draw a line between two points
   - Parameters: `x1`, `y1`, `x2`, `y2`
   - Returns: Object ID of created line

2. **create_circle** - Draw a circle
   - Parameters: `center_x`, `center_y`, `radius`
   - Returns: Object ID of created circle

3. **create_rectangle** - Draw a rectangle
   - Parameters: `x`, `y`, `width`, `height`
   - Returns: List of object IDs (polyline + entities)

4. **create_text** - Add text annotation
   - Parameters: `text`, `x`, `y`, `height`
   - Returns: Object ID of created text

### Layer Management

5. **create_layer** - Create a new layer
   - Parameters: `layer_name`
   - Returns: Layer name (or error if exists)

6. **list_layers** - List all layers in document
   - No parameters
   - Returns: List of layer names

### Analysis & Measurement

7. **calculate_area** - Calculate area of closed shape
   - Parameters: `object_id`
   - Returns: Calculated area value

### Document Operations

8. **save_drawing** - Save active drawing
   - Parameters: `file_path` (optional, defaults to current)
   - Returns: Success message with file path

9. **export_pdf** - Export drawing to PDF
   - Parameters: `output_path`
   - Returns: Success message with PDF path

10. **get_active_document** - Get active document info
    - No parameters
    - Returns: Document name and full path

## Installation

### Prerequisites

- **Windows 10/11** (AutoCAD COM API is Windows-only)
- **AutoCAD 2020+** installed and running
- **Python 3.11+** with pip
- **uv** package manager (recommended)

### Step 1: Clone Repository

```bash
git clone https://github.com/yourusername/autocad-mcp-server.git
cd autocad-mcp-server
```

### Step 2: Install Dependencies

Using **uv** (fastest):
```bash
uv sync
```

Or using **pip**:
```bash
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
```

### Step 3: Install pywin32 COM Support

After installing pywin32, register COM components:

```bash
python -m pip install --upgrade pywin32
python Scripts/pywin32_postinstall.py -install
```

Or if using uv:
```bash
uv run python -m pip install --upgrade pywin32
uv run python Scripts/pywin32_postinstall.py -install
```

### Step 4: Verify Installation

```bash
# Test that AutoCAD COM is accessible
python -c "import win32com.client; acad = win32com.client.GetObject(class='AutoCAD.Application'); print(f'AutoCAD {acad.Version} detected')"
```

## AutoCAD Prerequisites

### 1. AutoCAD Must Be Running

The server connects to a running AutoCAD instance via COM:

```bash
# Start AutoCAD before running the MCP server
# AutoCAD will be running in the background
```

### 2. Enable COM Automation (Usually Default)

AutoCAD COM is enabled by default. To verify:
1. Open AutoCAD
2. Go to **Tools** → **Options** → **System**
3. Ensure "OLE Support" is **enabled**

### 3. AutoCAD COM Version Support

| AutoCAD Version | COM Version | Python Support |
|---|---|---|
| 2024 | 24.x | ✅ Yes |
| 2023 | 23.x | ✅ Yes |
| 2022 | 22.x | ✅ Yes |
| 2021 | 21.x | ✅ Yes |
| 2020 | 20.x | ✅ Yes |

## Configuration

### Environment Variables

Create a `.env` file (copy from `.env.example`):

```env
# AutoCAD connection timeout in seconds
AUTOCAD_TIMEOUT=10

# Connection retry attempts
RETRY_ATTEMPTS=3

# Logging level: DEBUG, INFO, WARNING, ERROR
LOG_LEVEL=INFO

# Server host and port
MCP_HOST=127.0.0.1
MCP_PORT=8000
```

## Usage

### Option 1: Run as Standalone MCP Server

```bash
# Terminal 1: Start AutoCAD (if not already running)
# Open AutoCAD manually

# Terminal 2: Start MCP server
python -m src.server
```

The server will:
- Detect running AutoCAD instance
- Register all tools with MCP
- Listen for tool calls
- Reconnect if AutoCAD restarts

### Option 2: Claude Desktop Integration

#### Step 1: Get Server URL

When running locally, the server is available at:
```
stdio://python -m src.server
```

#### Step 2: Configure Claude Desktop

Edit `~/.config/Claude/claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "autocad": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "d:/autocad-mcp-server"
    }
  }
}
```

On Windows, the config is at:
```
C:\Users\[YourUsername]\AppData\Roaming\Claude\claude_desktop_config.json
```

#### Step 3: Restart Claude Desktop

Close and reopen Claude Desktop. The AutoCAD tools will appear in the Tools section.

### Option 3: ChatGPT Custom Actions

Create a custom action in ChatGPT with this schema pointing to your running MCP server.

### Option 4: Cursor IDE Integration

In Cursor settings, configure the MCP server endpoint:
```json
{
  "mcpServers": {
    "autocad": {
      "command": "python",
      "args": ["-m", "src.server"]
    }
  }
}
```

## Example Prompts

Once connected, use natural language to control AutoCAD:

### Basic Drawing

- "Draw a line from (0, 0) to (100, 50)"
  → Calls `create_line` with coordinates

- "Create a circle at center (50, 50) with radius 25"
  → Calls `create_circle`

- "Draw a 100x50 rectangle at origin"
  → Calls `create_rectangle`

### Text & Annotation

- "Add text 'WALL-A' at coordinates (10, 20) with height 5"
  → Calls `create_text`

### Layer Management

- "Create a new layer called 'Fixtures'"
  → Calls `create_layer`

- "Show me all layers in the drawing"
  → Calls `list_layers`

### Analysis

- "Calculate the area of object with ID 'ABC123'"
  → Calls `calculate_area`

### Document Management

- "Save the drawing"
  → Calls `save_drawing`

- "Export the drawing to PDF at C:\output\plan.pdf"
  → Calls `export_pdf`

- "What's the active document name?"
  → Calls `get_active_document`

## Troubleshooting

### Issue: "AutoCAD not found" or Connection Refused

**Solution:**
1. Open AutoCAD manually before starting the MCP server
2. Verify AutoCAD is running: Task Manager → search for "acad"
3. Check AutoCAD version supports COM (2020+)

```bash
# Debug: Test COM access
python -c "from src.autocad_client import AutoCADClient; c = AutoCADClient(); print(c.get_document_info())"
```

### Issue: "Module not found" errors

**Solution:**
```bash
# Reinstall dependencies
pip install -r requirements.txt

# Or with uv
uv sync --reinstall
```

### Issue: pywin32 COM not registered

**Solution:**
```bash
python -m pip install --upgrade pywin32
python Scripts/pywin32_postinstall.py -install

# On some systems, run as Administrator
```

### Issue: "Permission denied" when saving files

**Solution:**
1. Ensure the output directory exists and is writable
2. Run AutoCAD as Administrator if needed
3. Check file paths use forward slashes or double backslashes:
   ```python
   # Good
   "C:/output/drawing.pdf"
   "C:\\output\\drawing.pdf"
   
   # Bad
   "C:\output\drawing.pdf"  # Single backslashes interpreted as escape codes
   ```

### Issue: MCP Server won't start

**Solution:**
1. Check Python version: `python --version` (should be 3.11+)
2. Verify dependencies: `pip list | grep -E "fastmcp|pyautocad|pydantic"`
3. Check logs:
   ```bash
   # Run with DEBUG logging
   LOG_LEVEL=DEBUG python -m src.server
   ```

### Issue: Tools not appearing in Claude Desktop

**Solution:**
1. Verify config file exists: `C:\Users\[You]\AppData\Roaming\Claude\claude_desktop_config.json`
2. Check JSON syntax is valid (use [jsonlint.com](https://jsonlint.com))
3. Restart Claude Desktop completely
4. Check server logs for startup errors

### Issue: AutoCAD crashes or becomes unresponsive

**Solution:**
1. The server includes timeout and error handling
2. If AutoCAD freezes, kill the process and restart
3. Server will automatically reconnect when AutoCAD restarts
4. Check for unsupported AutoCAD operations (e.g., complex geometry)

## Testing

Run the unit test suite:

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=src

# Run specific test file
pytest tests/test_models.py

# Run with verbose output
pytest -v
```

Test coverage includes:
- ✅ Pydantic model validation
- ✅ Tool parameter validation
- ✅ AutoCAD connection logic
- ✅ API endpoint functionality
- ✅ Error handling and edge cases

## Project Structure

```
autocad-mcp-server/
├── src/
│   ├── __init__.py
│   ├── server.py                 # MCP server entrypoint
│   ├── autocad_client.py         # AutoCAD COM wrapper
│   ├── models.py                 # Pydantic validation models
│   └── tools/
│       ├── __init__.py           # Tool registry
│       ├── drawing.py            # Line, circle, rectangle, text
│       ├── layers.py             # Layer management
│       ├── dimensions.py         # Area calculation
│       └── export.py             # Save and PDF export
├── tests/
│   ├── test_models.py            # Model validation tests
│   ├── test_server.py            # API endpoint tests
│   └── test_tools.py             # Tool handler tests
├── pyproject.toml                # uv/pip dependencies
├── .env.example                  # Environment template
└── README.md                      # This file
```

## Architecture

### AutoCAD Connection

```
┌─────────────────────────────────────────┐
│     Claude Desktop / ChatGPT / etc      │
└──────────────────┬──────────────────────┘
                   │
                   │ (MCP Protocol)
                   │
┌──────────────────▼──────────────────────┐
│     MCP Server (FastMCP)                │
│  ├─ Tool Registry                       │
│  ├─ Request Dispatcher                  │
│  └─ Pydantic Validators                 │
└──────────────────┬──────────────────────┘
                   │
                   │ (Python API)
                   │
┌──────────────────▼──────────────────────┐
│     AutoCAD Client (pyautocad)          │
│  ├─ Connection Manager                  │
│  ├─ Retry Logic                         │
│  └─ Error Handler                       │
└──────────────────┬──────────────────────┘
                   │
                   │ (COM Automation)
                   │
┌──────────────────▼──────────────────────┐
│     AutoCAD Application (COM)           │
│  ├─ Drawing API                         │
│  ├─ Layer Management                    │
│  └─ Document Operations                 │
└─────────────────────────────────────────┘
```

## Performance Notes

- **Fast** - Direct COM calls, no network overhead
- **Lightweight** - Minimal dependencies
- **Reliable** - Auto-reconnection on AutoCAD restart
- **Safe** - Full input validation with Pydantic
- **Concurrent** - Handles multiple AI assistant requests

## Security Considerations

- ✅ Runs locally on Windows (no cloud exposure)
- ✅ Input validation on all tool parameters
- ✅ Type-safe with Pydantic models
- ✅ Error handling prevents information leakage
- ⚠️ AutoCAD file access - ensure proper file permissions
- ⚠️ When exposing via network, use authentication/TLS

## Contributing

Pull requests welcome! Areas for enhancement:

- [ ] Additional drawing primitives (arc, polyline, spline)
- [ ] Block/component support
- [ ] Dimension annotations
- [ ] Hatch patterns
- [ ] Custom properties
- [ ] Multi-document support
- [ ] macOS/Linux via parallel AutoCAD alternatives

## License

MIT - See LICENSE file

## Support

- 📧 **Issues:** GitHub Issues
- 💬 **Discussions:** GitHub Discussions
- 📚 **Docs:** [AutoCAD COM API Reference](https://help.autodesk.com/view/OARX/2024/ENU/)
- 🔗 **MCP Protocol:** [Model Context Protocol Spec](https://spec.modelcontextprotocol.io)

## Changelog

### v1.0.0 (2026-06-05)
- Initial release
- 10 core CAD tools
- Claude Desktop integration
- Full test coverage
- Production-ready code

## Roadmap

- [ ] AutoCAD Web API support for cloud deployments
- [ ] Real-time drawing updates with WebSocket
- [ ] Advanced geometry operations (offset, trim, extend)
- [ ] Material/property management
- [ ] CAM integration
- [ ] Version control for drawing changes

---

**Made with ❤️ for AI-powered CAD automation**