AutoCAD MCP Server

Máy chủ MCP cho tự động hóa AutoCAD LT và tạo DXF headless.

Một API, hai backend vẽ và hai transport kết nối:

Server cung cấp 8 công cụ (drawing, entity, layer, block, annotation, pid, view, system) với dispatch theo operation. Phiên bản runtime: 3.1 (LISP dispatcher reliability v3.2).

Prerequisites

Backend File IPC (AutoCAD thật)

• Windows 10/11 (không dùng WSL Python cho File IPC)

• AutoCAD LT 2024+ trên Windows — AutoLISP chỉ có từ LT 2024; AutoCAD LT cho Mac không hỗ trợ AutoLISP

• Python 3.10+ (native Windows)

• uv package manager

Backend ezdxf (headless)

Chạy trên Linux, macOS, WSL hoặc Windows — không cần AutoCAD, chỉ tạo/sửa DXF offline.

Quick Start

1. Clone và cài đặt

git clone https://github.com/sontakmtp-cell/autocad-mcp.git
cd autocad-mcp
uv sync

2. Auto-load LISP dispatcher (mỗi document)

State AutoLISP thuộc từng bản vẽ. Load mcp_dispatch.lsp một lần không đủ khi mở/tạo DWG mới. Cấu hình startup theo document:

1. Thêm <repo>/lisp-code vào Support File Search Path.

2. Thêm cùng thư mục vào TRUSTEDPATHS. Không tắt SECURELOAD.

3. Copy lisp-code/acadltdoc.lsp.example thành acadltdoc.lsp trong một Support File Search Path.

4. Restart AutoCAD LT, mở bản vẽ. Mỗi document nên in:

=== MCP Dispatch v3.2 reliability overrides loaded ===

Example dùng (findfile "mcp_dispatch.lsp") rồi (load ...), không hard-code path máy. Startup Suite / APPLOAD lặp lại không cần. Nếu document đang active thiếu dispatcher, MCP báo dispatcher_missing_in_active_document — server không tự mở APPLOAD.

3. Cấu hình MCP client (stdio)

Ví dụ claude_desktop_config.json:

{
  "mcpServers": {
    "autocad-mcp": {
      "command": "C:\\path\\to\\autocad-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "autocad_mcp"],
      "env": { "AUTOCAD_MCP_BACKEND": "auto" }
    }
  }
}

• command phải trỏ tới Windows Python trong venv

• Không dùng WSL Python khi cần File IPC

Client chạy trong WSL

Khởi động server qua cmd.exe + Windows Python:

{
  "mcpServers": {
    "autocad-mcp": {
      "type": "stdio",
      "command": "cmd.exe",
      "args": [
        "/d",
        "/s",
        "/c",
        "cd /d C:\\path\\to\\autocad-mcp && .venv\\Scripts\\python.exe -m autocad_mcp"
      ],
      "env": { "AUTOCAD_MCP_BACKEND": "auto" }
    }
  }
}

4. Kiểm tra

Từ MCP client:

system(operation="status")

• backend: "file_ipc" — AutoCAD đang chạy và được phát hiện

• backend: "ezdxf" — chế độ headless

Diagnostics bổ sung:

system(operation="health")
system(operation="tool_manifest")
system(operation="runtime")

Transport HTTP (ChatGPT / remote)

Transport mặc định vẫn là stdio. Để mở MCP qua mạng:

Dev demo (No Authentication)

$env:AUTOCAD_MCP_BACKEND = "ezdxf"   # hoặc auto / file_ipc
$env:AUTOCAD_MCP_TRANSPORT = "streamable-http"
$env:AUTOCAD_MCP_HOST = "127.0.0.1"
$env:AUTOCAD_MCP_PORT = "8765"
$env:AUTOCAD_MCP_PATH = "/mcp"
$env:AUTOCAD_MCP_REMOTE_PROFILE = "dev"
$env:AUTOCAD_MCP_AUTH_MODE = "none"
$env:AUTOCAD_MCP_ALLOW_NO_AUTH = "1"
$env:AUTOCAD_MCP_ALLOWED_HOSTS = "127.0.0.1"

uv run python -m autocad_mcp

Hoặc dùng script tunnel Phase 3:

powershell -ExecutionPolicy Bypass -File .\scripts\run-phase3-dev.ps1

Production OAuth + ChatGPT

Server là resource server (không tự host login). Cần OIDC provider (Auth0, Okta, Cognito, …) phát hành JWT + JWKS.

powershell -ExecutionPolicy Bypass -File .\scripts\run-phase4-oauth.ps1 `
  -PublicBaseUrl "https://cad.example.com" `
  -OAuthIssuer "https://issuer.example" `
  -OAuthAudience "https://cad.example.com"

• Endpoint MCP: https://cad.example.com/mcp

• Metadata: https://cad.example.com/.well-known/oauth-protected-resource

• Scopes: autocad.read, autocad.write

• execute_lisp mặc định bị chặn trên mọi remote profile; chỉ bật khi set AUTOCAD_MCP_ALLOW_EXECUTE_LISP=1 (rủi ro cao — AutoLISP tùy ý trên máy host)

Kết nối ChatGPT (Windows — khuyến nghị)

ChatGPT gọi MCP qua HTTPS công khai. MCP chỉ bind 127.0.0.1:8765; cần Cloudflare named tunnel (không dùng Quick Tunnel *.trycloudflare.com cho OAuth domain cố định).

Cài cloudflared (một lần):

winget install --id Cloudflare.cloudflared

Mỗi phiên làm việc — 2 cửa sổ:

start_cloudflare_tunnel.bat gọi scripts/setup-cloudflare-tunnel.ps1:

1. Mở browser / in link Cloudflare login nếu chưa có ~\.cloudflared\cert.pem

2. Chọn zone domain (ví dụ kythuatvang.com) → Authorize

3. Tạo/chọn named tunnel, ghi config.yml (hostname → http://127.0.0.1:8765)

4. Route DNS (ghi đè record cũ bằng CNAME tunnel nếu cần)

5. Chạy tunnel (giữ cửa sổ mở)

URL gắn vào ChatGPT Developer mode (OAuth):

https://cad.kythuatvang.com/mcp

(Wrapper start_mcp_chatgpt.bat đang cấu hình site-specific cho domain/issuer Auth0 của repo này — chỉnh bat/script nếu dùng domain khác.)

Kiểm tra public trước khi connect ChatGPT:

curl.exe -sS -i "https://cad.kythuatvang.com/.well-known/oauth-protected-resource"
# kỳ vọng: 200 + JSON scopes/issuer

curl.exe -sS -i "https://cad.kythuatvang.com/mcp"
# kỳ vọng: 401 khi chưa có token (OAuth bật)

Tuỳ chọn PowerShell:

# Chỉ setup, không giữ tunnel
powershell -ExecutionPolicy Bypass -File .\scripts\setup-cloudflare-tunnel.ps1 -SkipRun

# Hostname / tunnel name tuỳ chỉnh
powershell -ExecutionPolicy Bypass -File .\scripts\setup-cloudflare-tunnel.ps1 `
  -Hostname "cad.example.com" -TunnelName "autocad-mcp"

Chi tiết OAuth/policy: docs/phase2-remote-policy.md, docs/phase4-oauth.md, docs/ke-hoach-chatgpt-http-bridge.md.

AUTOCAD_MCP_TRANSPORT=sse được nhận trong config nhưng chưa implement — dùng stdio hoặc streamable-http.

Tools

Mỗi tool nhận operation (string) và thường có data (object) + include_screenshot (bool).

drawing — Quản lý file bản vẽ

entity — Đối tượng hình học

Tạo: create_line, create_circle, create_polyline, create_rectangle, create_arc, create_ellipse, create_mtext, create_hatch

Đọc: list, count, get

Sửa: copy, move, rotate, scale, mirror, offset*, array, fillet*, chamfer*, erase

* offset, fillet, chamfer chỉ File IPC.

layer — Layer

list, create, set_current, set_properties, freeze, thaw, lock, unlock

block — Block

annotation — Chú thích & auto-dimension

Cơ bản

• create_text

• create_dimension_linear / aligned / angular / radius

• create_leader

Workflow dimension tự động (part-aware)

Selector cho plan/auto (chọn một): target_part_id | entity_ids | region | selection: "current".

Profile built-in: mechanical_mm, mechanical_inch, iso_simple. Profile tùy chỉnh mặc định lưu tại %LOCALAPPDATA%\autocad-mcp\dimension_profiles.json (hoặc AUTOCAD_MCP_DIMENSION_PROFILES).

Chi tiết và ví dụ JSON: docs/auto-dimension.md.

pid — P&ID (thư viện CTO)

setup_layers, insert_symbol, list_symbols, draw_process_line, connect_equipment, add_flow_arrow, add_equipment_tag, add_line_number, insert_valve, insert_instrument, insert_pump, insert_tank

Cần cài thư viện CAD Tools Online vào:

C:\PIDv4-CTO\

view — Viewport & screenshot

• File IPC: Win32 PrintWindow (kể cả khi AutoCAD minimize)

• ezdxf: matplotlib render

system — Server

Ví dụ execute_lisp:

system(operation="execute_lisp", data={"code": "(+ 1 2)"})

Architecture

MCP Client (Claude / ChatGPT / …)
        │
        ├── stdio (JSON-RPC)          ← mặc định
        └── streamable-http (/mcp)    ← remote + tunnel HTTPS
                │
                ▼
        remote policy / OAuth / path guard
                │
                ▼
     Python MCP Server (autocad_mcp 3.1)
                │
        ├── File IPC Backend (Windows)
        │         │  C:/temp/*session*/*request*.json
        │         ▼
        │   mcp_dispatch.lsp (AutoCAD LT)
        │   + auto_dimension*.lsp
        │
        └── ezdxf Backend
                  ▼
             in-memory DXF

File IPC

• Route expression whitelist qua ActiveX: ưu tiên Document.PostCommand, fallback tường minh Document.SendCommand

• Không dùng keyboard, clipboard, focus hay WM_CHAR

• Trước khi gửi: kiểm tra IsQuiescent / CMDACTIVE → autocad_busy nếu user đang có lệnh (MCP không gửi ESC)

• Request file mang process/session ID + request ID; LISP mở đúng file đó

Mã lỗi ổn định: docs/file-ipc-error-model.md.
Checklist tay: docs/file-ipc-manual-test.md.

Environment Variables

Backend & IPC

Nếu đổi AUTOCAD_MCP_IPC_DIR, cập nhật tương ứng biến *mcp-ipc-dir* trong lisp-code/mcp_dispatch.lsp.

Transport & remote

Development

uv sync
uv run pytest tests/ -v

CI: .github/workflows/test.yml.

Script hỗ trợ:

AutoCAD LT AutoLISP Compatibility

AutoLISP có trên AutoCAD LT 2024+ (Windows).

Một số đường dimension tối ưu dùng ActiveX khi có; xem lisp-code/auto_dimension_activex.lsp.

Documentation

What's included (current)

• 8 tool MCP thống nhất, operation dispatch

• Dual backend: File IPC + ezdxf

• Dual transport: stdio + Streamable HTTP

• Remote policy (dev No-Auth allowlist, production OAuth scopes)

• ChatGPT path: OAuth MCP + Cloudflare named tunnel helpers (start_cloudflare_tunnel.bat)

• Part-aware auto-dimension: detect → plan → commit / one-shot / audit-repair

• File IPC reliability: session/request IDs, structured error_code, per-document dispatcher probe

• system.tool_manifest / runtime / health diagnostics

• execute_lisp cho automation mở rộng (local only)

• Wheel packaging kèm lisp-code (hatchling force-include)

License

MIT