# AutoCAD MCP Server - Complete Documentation

🏗️ **A powerful Python-based Model Context Protocol (MCP) server that provides programmatic control over AutoCAD through COM automation.**

**Youtube video of the working demo**
https://www.youtube.com/watch?v=KQpxiXvF4cc

Transform your AutoCAD workflow with intelligent building structure creation, automatic layer management, and comprehensive entity manipulation - all through Claude and other MCP clients.

## 🚀 Quick Start (30 seconds)

```bash
# 1. Clone and setup
git clone https://github.com/yourusername/autocad-mcp-server
cd autocad-mcp-server
pip install -e .

# 2. Start AutoCAD (must be running)
# Open AutoCAD application

# 3. Test the server
python test_script.py
```

## 📋 Table of Contents

- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration with Claude Desktop](#configuration-with-claude-desktop)
- [Running the Server](#running-the-server)
- [Basic Usage Examples](#basic-usage-examples)
- [Advanced Features](#advanced-features)
- [API Reference](#api-reference)
- [Troubleshooting](#troubleshooting)
- [Development](#development)

## Prerequisites

### System Requirements
- **Operating System**: Windows (COM automation requirement)
- **AutoCAD**: Any version 2000+ with COM support
- **Python**: 3.8 or higher
- **Claude Desktop**: Latest version (for MCP integration)

### Required Software
1. **AutoCAD Installation**
   - Any AutoCAD version (AutoCAD, AutoCAD LT, Civil 3D, etc.)
   - Must have valid license and be able to run
   - COM automation must be enabled (default in most installations)

2. **Python Environment**
   - Python 3.8+ installed
   - Administrative privileges may be required for COM registration

## Installation

### Method 1: Using pip (Recommended)

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

# Create virtual environment
python -m venv venv

# Activate environment (Windows)
venv\Scripts\activate

# Install the package
pip install -e .
```

### Method 2: Using uv (Faster)

```bash
# Install uv if not already installed
pip install uv

# Clone and setup
git clone https://github.com/yourusername/autocad-mcp-server
cd autocad-mcp-server

# Create environment and install
uv venv
uv pip install -e .
```

### Dependencies Installed
- `mcp>=1.0.0` - Model Context Protocol framework
- `pywin32>=306` - Windows COM automation

## Configuration with Claude Desktop

### Step 1: Locate Claude Desktop Config

Find your Claude Desktop configuration file:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

### Step 2: Add MCP Server Configuration

Edit the config file to include your AutoCAD MCP server:

```json
{
  "mcpServers": {
    "autocad-mcp": {
      "command": "python",
      "args": [
        "C:\\path\\to\\your\\autocad-mcp-server\\test_script.py"
      ],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\your\\autocad-mcp-server"
      }
    }
  }
}
```

**Important**: Replace `C:\\path\\to\\your\\autocad-mcp-server` with your actual project path.

### Step 3: Alternative Configuration (If Installed via pip)

If you installed the package globally:

```json
{
  "mcpServers": {
    "autocad-mcp": {
      "command": "autocad-mcp",
      "args": []
    }
  }
}
```

### Step 4: Restart Claude Desktop

1. Close Claude Desktop completely
2. Restart the application
3. Verify the MCP server appears in available tools

## Running the Server

### Method 1: Standalone Testing

```bash
# Activate your environment
venv\Scripts\activate  # Windows
# source venv/bin/activate  # macOS/Linux

# Start AutoCAD first (important!)
# Open AutoCAD application

# Run the test script
python test_script.py
```

**Expected Output:**
```
✅ Successfully connected to AutoCAD
📄 Drawing: Drawing1.dwg
📊 Entities: 0
🚀 MCP Server starting...
Server running and waiting for client connections...
```

### Method 2: Through Claude Desktop

1. **Start AutoCAD** (must be running before Claude connects)
2. **Open Claude Desktop**
3. **Start new conversation**
4. **Verify MCP connection** - You should see "autocad-mcp" in available tools
5. **Test with a simple command**:

```
Hi! Can you check what AutoCAD drawing is currently open?
```

### Method 3: Direct MCP Client

For advanced users or custom integrations:

```python
import asyncio
from autocad_mcp import AutoCADCOMServer

async def run_server():
    server = AutoCADCOMServer()
    await server.main()

asyncio.run(run_server())
```

## Basic Usage Examples

### Through Claude Desktop

Once configured, you can use natural language with Claude to control AutoCAD:

#### Example 1: Check Drawing Status
```
Claude: Can you tell me about the current AutoCAD drawing?
```

**Claude will use the MCP server to get drawing information and respond with details about the current drawing, layers, and entity count.**

#### Example 2: Create a Simple Room
```
Claude: Create a 12x10 foot room with walls that are 6 inches thick. Add a door on the south wall and a window on the east wall.
```

**Claude will:**
- Create a room structure using `create_structure`
- Add walls with proper thickness
- Place door and window openings
- Use appropriate layers (WALLS, DOORS, WINDOWS)
- Label the elements

#### Example 3: Layer Management
```
Claude: Show me all the layers in the current drawing and create a new layer called "HVAC" with red color.
```

#### Example 4: Entity Querying
```
Claude: List all the entities in the drawing grouped by layer. How many walls do we have?
```

### Direct API Usage (Advanced)

If you're building custom applications:

```python
from autocad_mcp import AutoCADCOMServer

# Initialize server
server = AutoCADCOMServer()

# Connect to AutoCAD
if server.connect_to_autocad():
    
    # Create a wall
    result = server.create_structure(
        structure_type="wall",
        geometry_data={
            "start": [0, 0],
            "end": [20, 0]
        },
        thickness=0.5,
        label="North Wall"
    )
    
    # Create a door
    door_result = server.create_structure(
        structure_type="door", 
        geometry_data={
            "start": [8, 0],
            "end": [11, 0],
            "width": 3
        },
        label="Main Entrance"
    )
    
    # Get all entities
    entities = server.get_entities()
    print(f"Total entities: {entities['total_count']}")
```

## Advanced Features

### Intelligent Layer Management

The server automatically assigns structures to appropriate layers:

```python
# Automatically goes to WALLS layer
create_structure("wall", geometry_data)

# Automatically goes to ELECTRICAL layer  
create_structure("outlet", geometry_data)

# Custom layer assignment
create_structure("furniture", geometry_data, custom_layer="BEDROOM_FURNITURE")
```

### Thickness and Styling

```python
# Wall with thickness (creates parallel lines with end caps)
create_structure("wall", {
    "start": [0, 0], 
    "end": [20, 0]
}, thickness=0.5, color="white")

# Circle with thickness (creates concentric circles)
create_circle([10, 10], 5, color="red", thickness=0.2)
```

### Batch Operations

```python
# Get all entities
entities = get_entities()

# Delete by criteria
delete_entities_by_layer("TEMP_LAYER")
delete_entities_by_color("red")
delete_entities_by_type("AcDbText")

# Modify existing entities
for entity in entities['entities']:
    if entity['type'] == 'AcDbLine':
        change_entity_color(entity['handle'], 'blue')
```

### Structure Labeling

```python
# Create room with automatic labeling
create_structure("room", {
    "corner1": [0, 0],
    "corner2": [12, 8]
}, label="Living Room", thickness=0.25)

# Labels automatically go to ANNOTATION layer
```

## API Reference

### Core Information Tools

#### `get_drawing_info()`
**Purpose**: Get comprehensive drawing information
**Returns**: Drawing metadata, layer info, entity counts

```python
{
  "filename": "floor_plan.dwg",
  "path": "C:\\Projects\\floor_plan.dwg", 
  "entity_count": 150,
  "saved": true,
  "current_layer": "WALLS",
  "total_layers": 8,
  "available_layers": [...]
}
```

#### `get_entities(max_entities?)`
**Purpose**: Retrieve all entities with layer grouping
**Parameters**: 
- `max_entities` (optional): Limit number of entities returned

**Returns**: Complete entity list with metadata
```python
{
  "entities": [...],
  "entities_by_layer": {
    "WALLS": [25 entities],
    "DOORS": [8 entities]
  },
  "total_count": 150,
  "layer_summary": {"WALLS": 25, "DOORS": 8}
}
```

### Structure Creation

#### `create_structure(type, geometry, options)`
**Purpose**: Create intelligent building structures
**Parameters**:
- `structure_type`: "wall", "door", "window", "room", "furniture", etc.
- `geometry_data`: Geometry definition
- `color` (optional): Override default layer color
- `thickness` (optional): Structure thickness  
- `custom_layer` (optional): Custom layer name
- `label` (optional): Text label

**Examples**:
```python
# Wall
create_structure("wall", {
    "start": [0, 0], "end": [20, 0]
}, thickness=0.25, label="Exterior Wall")

# Room  
create_structure("room", {
    "corner1": [0, 0], "corner2": [12, 10]
}, label="Master Bedroom")

# Door with swing
create_structure("door", {
    "start": [8, 0], "end": [11, 0], "width": 3
}, label="Front Door")
```

### Basic Entity Creation

#### `create_line(start, end, color?, thickness?)`
```python
create_line([0, 0], [10, 0], "red", 0.1)
```

#### `create_circle(center, radius, color?, thickness?)`
```python
create_circle([5, 5], 3, "blue", 0.05)
```

#### `create_rectangle(corner1, corner2, color?, thickness?)`
```python
create_rectangle([0, 0], [10, 8], "green", 0.0)
```

#### `create_text(position, text, height?, color?)`
```python
create_text([5, 5], "Room Label", 0.5, "black")
```

#### `create_arc(center, radius, start_angle, end_angle, color?, thickness?)`
```python
create_arc([0, 0], 5, 0, 90, "cyan", 0.0)
```

### Layer Management

#### `create_or_get_layer(name, color?, description?)`
```python
create_or_get_layer("CUSTOM_LAYER", "yellow", "Custom elements")
```

#### `set_current_layer(name)`
```python
set_current_layer("WALLS")
```

### Entity Deletion

#### `delete_entity_by_handle(handle)`
```python
delete_entity_by_handle("ABC123")
```

#### `delete_entities_by_layer(layer_name)`
```python
delete_entities_by_layer("TEMP_LAYER")
```

#### `delete_entities_by_type(entity_type)`
```python
delete_entities_by_type("AcDbText")  # Delete all text
```

#### `delete_entities_by_color(color)`
```python
delete_entities_by_color("red")
```

#### `delete_last_entities(count?)`
```python
delete_last_entities(5)  # Delete last 5 entities
```

### Utility Tools

#### `undo_last_operation()`
```python
undo_last_operation()  # Ctrl+Z equivalent
```

#### `change_entity_color(handle, color)`
```python
change_entity_color("ABC123", "blue")
```

#### `zoom_extents()`
```python
zoom_extents()  # Zoom to show all objects
```

## Predefined Layer System

| Layer Name | Color | Purpose |
|------------|-------|---------|
| WALLS | White | Building walls and partitions |
| DOORS | Green | Door openings and frames |
| WINDOWS | Cyan | Window openings and frames |
| FURNITURE | Yellow | Furniture and fixtures |
| ELECTRICAL | Red | Electrical fixtures and outlets |
| PLUMBING | Blue | Plumbing fixtures and pipes |
| HVAC | Magenta | HVAC ducts and equipment |
| STRUCTURE | Gray | Structural elements |
| ANNOTATION | White | Text and dimensions |
| SITE | Green | Site elements and landscaping |
| UTILITIES | Red | Utility lines and equipment |

### Automatic Layer Assignment

The system intelligently assigns layers based on keywords:

```python
structure_mapping = {
    "wall", "partition" → "WALLS",
    "door", "opening" → "DOORS", 
    "window" → "WINDOWS",
    "furniture", "chair", "table", "bed" → "FURNITURE",
    "outlet", "switch", "light" → "ELECTRICAL",
    "toilet", "sink", "pipe" → "PLUMBING",
    "vent", "duct", "hvac" → "HVAC",
    "beam", "column" → "STRUCTURE",
    "text", "dimension" → "ANNOTATION"
}
```

## Real-World Examples

### Example 1: Complete Floor Plan with Claude

**User to Claude:**
```
Create a simple apartment floor plan:
- 20x15 foot room with 6-inch walls
- Front door (3 feet wide) on the south wall, centered
- Two windows (4 feet each) on the east and west walls
- Kitchen area in the northwest corner (8x6 feet)
- Add labels for each area
```

**Claude's Response Process:**
1. Uses `create_structure("room", ...)` for main room
2. Uses `create_structure("door", ...)` for entrance  
3. Uses `create_structure("window", ...)` for windows
4. Uses `create_structure("room", ...)` for kitchen
5. Uses `create_text(...)` for labels
6. Uses `zoom_extents()` to show complete drawing

### Example 2: Layer Management Workflow

**User to Claude:**
```
I need to organize my drawing. Can you:
1. Show me all current layers and their entity counts
2. Move all red entities to a new "HIGHLIGHTED" layer
3. Delete everything on the "TEMP" layer
4. Change all text to be green colored
```

**Claude's Process:**
1. `get_entities()` to analyze current state
2. `create_or_get_layer("HIGHLIGHTED", "red")`
3. Filter entities by color, move to new layer
4. `delete_entities_by_layer("TEMP")`
5. `change_entity_color()` for all text entities

### Example 3: Electrical Layout

**User to Claude:**
```
Add electrical outlets and switches to this room:
- Outlets every 8 feet along the walls
- Light switches by each door
- Ceiling light in the center
- Put everything on the electrical layer with proper labels
```

**Claude's Process:**
1. `get_entities()` to find existing walls and doors
2. Calculate outlet positions along walls
3. `create_structure("outlet", ...)` for each outlet
4. `create_structure("switch", ...)` by doors
5. `create_structure("light", ...)` at room center
6. All automatically go to ELECTRICAL layer

## Troubleshooting

### Common Issues and Solutions

#### ❌ "Not connected to AutoCAD"

**Symptoms:**
- Error messages about AutoCAD connection
- Server fails to start

**Solutions:**
1. **Start AutoCAD First**
   ```bash
   # Always start AutoCAD before the MCP server
   # Open AutoCAD application manually
   ```

2. **Check AutoCAD Installation**
   ```bash
   # Verify AutoCAD is installed and licensed
   # Try opening AutoCAD manually
   ```

3. **Administrative Privileges**
   ```bash
   # Run command prompt as Administrator
   # Try running the server with elevated privileges
   ```

4. **COM Registration Issues**
   ```bash
   # Re-register AutoCAD COM components
   # Run as Administrator:
   regsvr32 "C:\Program Files\Autodesk\AutoCAD 202X\acad.exe" /regserver
   ```

#### ❌ Claude Desktop Not Connecting

**Symptoms:**
- MCP server not appearing in Claude
- Tools not available

**Solutions:**
1. **Check Configuration Path**
   ```json
   // Verify paths in claude_desktop_config.json are correct
   {
     "mcpServers": {
       "autocad-mcp": {
         "command": "python",
         "args": ["C:\\CORRECT\\PATH\\test_script.py"]
       }
     }
   }
   ```

2. **Restart Claude Desktop**
   - Close Claude completely (check system tray)
   - Restart the application
   - Wait for full initialization

3. **Check Python Environment**
   ```bash
   # Verify Python and dependencies are accessible
   python -c "import mcp; print('MCP available')"
   python -c "import win32com.client; print('COM available')"
   ```

4. **Test Server Standalone**
   ```bash
   # Test the server works independently
   python test_script.py
   ```

#### ❌ COM Timeout Errors

**Symptoms:**
- Operations taking too long
- "COM operation timed out" errors

**Solutions:**
1. **Close Unnecessary AutoCAD Drawings**
   - Keep only one drawing open
   - Close large/complex drawings

2. **Increase Delay Parameters**
   ```python
   # In server.py, increase delay in safe_operation
   def safe_operation(self, operation_func, delay: float = 2.0):  # Increased delay
   ```

3. **Process in Smaller Batches**
   ```python
   # For large operations, break into smaller chunks
   entities = get_entities(max_entities=100)  # Limit batch size
   ```

#### ❌ Layer Creation Issues

**Symptoms:**
- Layers not being created
- "Layer already exists" errors

**Solutions:**
1. **Check Drawing Permissions**
   - Ensure drawing is not read-only
   - Save the drawing first

2. **Verify Layer Names**
   ```python
   # Use valid layer names (no special characters)
   create_or_get_layer("VALID_LAYER_NAME", "white")
   ```

3. **Layer Naming Conflicts**
   - Check for existing layers with same name
   - Use unique layer names

#### ❌ Performance Issues

**Symptoms:**
- Slow response times
- High memory usage
- AutoCAD becomes unresponsive

**Solutions:**
1. **Optimize Entity Queries**
   ```python
   # Use max_entities for large drawings
   entities = get_entities(max_entities=500)
   
   # Query specific layers instead of all entities
   delete_entities_by_layer("TARGET_LAYER")
   ```

2. **Batch Operations**
   ```python
   # Group similar operations together
   handles = ["handle1", "handle2", "handle3"]
   delete_entities_by_handles(handles)  # Batch delete
   ```

3. **AutoCAD Settings**
   - Turn off automatic save during operations
   - Disable visual effects/animations
   - Close unnecessary AutoCAD palettes

### Debugging Tips

#### Enable Verbose Logging
```python
# Add to test_script.py for debugging
import logging
logging.basicConfig(level=logging.DEBUG)

# Add debug prints in operations
print(f"DEBUG: Operation started - {operation_name}")
```

#### Test Individual Components
```python
# Test AutoCAD connection separately
from autocad_mcp import AutoCADCOMServer
server = AutoCADCOMServer()
print(f"Connection: {server.connect_to_autocad()}")

# Test specific operations
result = server.create_line([0,0], [10,0])
print(f"Line creation: {result}")
```

#### Monitor AutoCAD State
```python
# Check AutoCAD responsiveness
info = server.get_drawing_info()
print(f"AutoCAD responsive: {'error' not in info}")
```

## Development

### Extending the Server

#### Adding New Structure Types

1. **Define Layer Mapping**
```python
# Add to layer_definitions in server.py
self.layer_definitions["custom_type"] = {
    "name": "CUSTOM_LAYER", 
    "color": "yellow", 
    "description": "Custom structure type"
}
```

2. **Create Structure Method**
```python
def create_custom_structure(self, geometry_data, color="yellow", thickness=0.0):
    """Create custom structure"""
    # Implementation here
    pass
```

3. **Add to Structure Mapping**
```python
# Add to get_layer_for_structure_type method
if "custom" in structure_type_lower:
    return "CUSTOM_LAYER"
```

4. **Update MCP Tools**
```python
# Add to setup_tools method
types.Tool(
    name="create_custom_structure",
    description="Create custom structure type",
    inputSchema={...}
)
```

#### Adding New Entity Properties

```python
def create_line_with_custom_properties(self, start, end, **kwargs):
    """Enhanced line creation with custom properties"""
    line = self.create_line(start, end, kwargs.get('color', 'white'))
    
    # Add custom properties
    if 'lineweight' in kwargs:
        line.Lineweight = kwargs['lineweight']
    
    if 'linetype' in kwargs:
        line.Linetype = kwargs['linetype']
    
    return line
```

### Testing

#### Unit Tests
```python
# tests/test_server.py
import unittest
from autocad_mcp import AutoCADCOMServer

class TestAutoCADServer(unittest.TestCase):
    def setUp(self):
        self.server = AutoCADCOMServer()
    
    def test_connection(self):
        result = self.server.connect_to_autocad()
        self.assertTrue(result)
    
    def test_layer_creation(self):
        result = self.server.create_or_get_layer("TEST_LAYER")
        self.assertTrue(result)
```

#### Integration Tests
```python
# Test complete workflows
def test_room_creation_workflow():
    server = AutoCADCOMServer()
    
    # Create room
    result = server.create_structure("room", {
        "corner1": [0, 0],
        "corner2": [10, 10]
    }, label="Test Room")
    
    assert result["success"]
    
    # Verify entities created
    entities = server.get_entities()
    assert entities["total_count"] > 0
```

### Performance Optimization

#### For Large Drawings
```python
# Batch processing for large operations
def process_large_dataset(self, data_list, batch_size=100):
    """Process large datasets in batches"""
    for i in range(0, len(data_list), batch_size):
        batch = data_list[i:i+batch_size]
        self.process_batch(batch)
        time.sleep(0.1)  # Prevent COM overload
```

#### Memory Management
```python
# Clean up COM objects explicitly
def cleanup_com_objects(self):
    """Clean up COM references"""
    if self.doc:
        self.doc = None
    if self.acad_app:
        self.acad_app = None
    pythoncom.CoUninitialize()
```

### Contributing

1. **Fork the repository**
2. **Create feature branch**: `git checkout -b feature/new-feature`
3. **Add tests** for new functionality
4. **Update documentation**
5. **Submit pull request**

#### Code Style
- Follow PEP 8 guidelines
- Use type hints where possible
- Add docstrings for all public methods
- Include error handling for COM operations

#### Testing Requirements
- All new features must include tests
- Maintain >90% code coverage
- Test with multiple AutoCAD versions if possible

## FAQ

### Q: Can I use this with AutoCAD LT?
**A**: Yes, AutoCAD LT supports COM automation and should work with this server.

### Q: Does this work with other CAD software?
**A**: This server is specifically designed for AutoCAD's COM interface. Other CAD software would require different implementations.

### Q: Can I run multiple instances?
**A**: You can connect to multiple AutoCAD instances, but each MCP server instance connects to one AutoCAD instance.

### Q: Is this compatible with AutoCAD on Mac?
**A**: No, this uses Windows COM automation which is not available on Mac. AutoCAD for Mac uses a different architecture.

### Q: Can I modify existing drawings?
**A**: Yes, the server can modify any drawing that AutoCAD can open, including reading entities, modifying properties, and adding new content.

### Q: How do I handle coordinate systems?
**A**: The server uses AutoCAD's current coordinate system. All coordinates are in AutoCAD's current units (typically decimal units).

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## Legal Notice

This software requires a valid AutoCAD license for operation. AutoCAD is a trademark of Autodesk, Inc. This project is not affiliated with or endorsed by Autodesk.

**Ready to revolutionize your AutoCAD workflow? Start creating intelligent drawings with Claude today!**