内容
# AutoCAD MCP 服务器
适用于 AutoCAD 2026 / AutoCAD LT 自动化、无头 DXF 生成和 AutoCAD Plant 3D 项目只读查询的 MCP 服务器。由 IDEA IT（Ingeniería y Diseño Estructural Avanzado, S.L.）开发。
两个后端，一个 API：
| 后端 | 运行时 | 是否需要 AutoCAD？ | 快照 |
|---------|---------|-------------------|------------|
| **文件 IPC** | Windows Python | 是 — AutoCAD LT 2024+ / AutoCAD 2026（Windows） | Win32 PrintWindow |
| **ezdxf** | 任意平台 | 否（无头） | matplotlib 渲染 |
服务器通过 MCP stdio 传输暴露 **9 个整合工具**（`drawing`、`entity`、`layer`、`block`、`annotation`、`pid`、`view`、`system`、`plant3d`）。MCP 客户端（Claude Desktop、Claude Code 等）连接并通过自然语言请求驱动 AutoCAD。
`plant3d` 工具直接在只读模式下查询 Plant 3D 项目数据库（`.dcf` SQLite 文件）- 不需要 .NET 插件或打开 AutoCAD 会话即可进行大多数操作。
## 先决条件（文件 IPC 后端）
- **Windows 10/11**（文件 IPC 后端使用 Win32 API 进行无焦点窗口消息）
- **AutoCAD LT 2024 或更新版本** - AutoLISP 支持在 LT 2024 for Windows 中添加。AutoCAD LT for Mac 存在但 **不支持** AutoLISP。
- **Python 3.10+**（Windows 原生 - 不是 WSL Python）
- **uv** 包管理器（[安装指南](https://docs.astral.sh/uv/getting-started/installation/)）
> ezdxf 无头后端在任何平台（Linux、macOS、WSL）上都适用于离线 DXF 生成，无需安装 AutoCAD。
## 快速入门
### 1. 克隆和安装
```powershell
git clone https://github.com/Romeraaa/autocadplant3d-mcp.git
cd autocadplant3d-mcp
uv sync
```
### 2. 在 AutoCAD LT 中加载 LISP 分发器
打开 AutoCAD LT 并使用 **APPLOAD** 加载 `mcp_dispatch.lsp`：
1. 在 AutoCAD 命令行中输入 `APPLOAD`
2. 浏览到 `<repo>/lisp-code/mcp_dispatch.lsp`
3. 点击 **加载**
4. 您应该看到：`=== MCP Dispatch v3.1 loaded ===` 和 `Ready for commands via (c:mcp-dispatch)`
> **提示：** 将文件添加到您的 AutoCAD 启动套件（在 APPLOAD 对话框中），以便它在每次绘图时自动加载。
### 3. 配置您的 MCP 客户端
将以下内容添加到您的 MCP 客户端配置（例如 Claude Desktop `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"autocad-mcp": {
"command": "C:\\path\\to\\autocadplant3d-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "autocad_mcp"],
"env": { "AUTOCAD_MCP_BACKEND": "auto" }
}
}
}
```
**关键点：**
- `command` 必须指向项目 venv 中的 **Windows Python**（不是 WSL python）。
- `AUTOCAD_MCP_BACKEND` 可以是 `auto`（默认 - 尝试文件 IPC，fallback 到 ezdxf），`file_ipc`（需要 AutoCAD）或 `ezdxf`（仅无头）。
#### 从 WSL 运行
如果您的 MCP 客户端在 WSL 中运行（例如 Claude Code），请通过 `cmd.exe` 启动服务器，以便它作为原生 Windows 进程运行：
```json
{
"mcpServers": {
"autocad-mcp": {
"type": "stdio",
"command": "cmd.exe",
"args": ["/d", "/s", "/c", "cd /d C:\\path\\to\\autocadplant3d-mcp && .venv\\Scripts\\python.exe -m autocad_mcp"],
"env": { "AUTOCAD_MCP_BACKEND": "auto" }
}
}
}
```
### 4. 验证
从您的 MCP 客户端调用：
```
system(operation="status")
```
如果 AutoCAD 正在运行，您应该看到 `backend: "file_ipc"`，否则为 `backend: "ezdxf"` 表示无头模式。
## 工具
### `drawing` — 文件/绘图管理
| 操作 | 描述 | 文件 IPC | ezdxf |
|-----------|-------------|----------|-------|
| `create` | 重置为干净的绘图（擦除所有内容 + 清除） | 是 | 是 |
| `open` | 打开现有的绘图 | 是 | 是（DXF） |
| `info` | 获取实体数量和图层 | 是 | 是 |
| `save` | 保存当前绘图（如果给出路径，则保存到该路径） | 是 | 是 |
| `save_as_dxf` | 导出为 DXF | 是 | 是 |
| `plot_pdf` | 打印到 PDF | 是 | 否 |
| `purge` | 清除未使用的对象 | 是 | 是 |
| `get_variables` | 按名称获取系统变量 | 是 | 是 |
| `undo` | 撤销上一次操作 | 是 | 否 |
| `redo` | 重做上一次撤销的操作 | 是 | 否 |
### `entity` — 实体 CRUD + 修改
**创建：** `create_line`、`create_circle`、`create_polyline`、`create_rectangle`、`create_arc`、`create_ellipse`、`create_mtext`、`create_hatch`
**读取：** `list`、`count`、`get`
**修改：** `copy`、`move`、`rotate`、`scale`、`mirror`、`offset`*、`array`、`fillet`*、`chamfer`*、`erase`
> \* `offset`、`fillet`、`chamfer` 仅限文件 IPC（不支持 ezdxf 无头后端）。
### `layer` — 图层管理
`list`、`create`、`set_current`、`set_properties`、`freeze`、`thaw`、`lock`、`unlock`
### `block` — 块操作
| 操作 | 文件 IPC | ezdxf |
|-----------|----------|-------|
| `list` | 是 | 是 |
| `insert` | 是 | 是 |
| `insert_with_attributes` | 是 | 是 |
| `get_attributes` | 是 | 是 |
| `update_attribute` | 是 | 是 |
| `define` | 否 | 是 |
### `annotation` — 文本、尺寸、引线
`create_text`、`create_dimension_linear`、`create_dimension_aligned`、`create_dimension_angular`、`create_dimension_radius`、`create_leader`
### `pid` — P&ID 操作（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`
> P&ID 符号插入需要 [CAD Tools Online](https://www.cadtoolsonline.com/) （CTO）P&ID 符号库安装在 `C:\PIDv4-CTO\`。ezdxf 后端具有内置的 CTO 库支持。对于文件 IPC 后端，一些 P&ID 操作需要额外的 LISP 帮助程序 - 有关设置的详细信息，请参见 wiki 中的 P&ID 部分。
### `view` — 视口和截图
| 操作 | 描述 |
|-----------|-------------|
| `zoom_extents` | 缩放以显示所有实体 |
| `zoom_window` | 缩放至指定窗口 |
| `get_screenshot` | 捕获当前 AutoCAD 视图为 PNG |
截图使用 `PrintWindow`（Win32）用于文件 IPC 后端 - 即使 AutoCAD 最小化或在后台，也能正常工作。ezdxf 后端通过 matplotlib 渲染。
### `system` — 服务器管理
`status`、`health`、`get_backend`、`runtime`、`init`、`execute_lisp`
> **警告：** `execute_lisp` 运行任意 AutoLISP 代码（仅限文件 IPC）。传递 `data: {code: "(+ 1 2)"}`。但是，在 AutoCAD 2026 上，它会触发 APPLOAD 对话框并阻塞线程 - **请勿使用**；使用原生 MCP 操作代替。
### `plant3d` — Plant 3D 项目查询（只读）
| 操作 | 描述 |
|-----------|-------------|
| `detect_project` | 解析 AutoCAD 中当前打开的 Plant 3D 项目（通过 `DWGPREFIX`）或通过显式路径/名称。 |
| `list_projects` | 列出在 `AUTOCAD_MCP_PLANT3D_ROOT` 下找到的 Plant 3D 项目。 |
| `line_summary` | 给定项目的每行组件摘要：计数、规格和直径按 `LineNumberTag`。 |
| `find_untagged` | 没有有效 `LineNumberTag` 的管道组件，按类和规格分解。 |
| `validate_specs` | 规格一致性检查：规格与所需规格、每行混合规格、空白/幽灵规格、材料/计划在规格目录外。 |
| `list_lines` | 项目线路列表 - 每行服务、规格、尺寸、绝缘和模型 DWG。 |
| `list_components` | 通用管道组件列表（`PipeRunComponent` ⨝ `EngineeringItems`）可选过滤器：`classes`（管道/阀门/配件/法兰/仪器/支持）、`line`、`spec`、`size`（需要单位）。返回 `pnpid`、`class`、`tag`、`description`、`spec`、`size`、`line` 每个组件，以及 `by_class` 概要和 `omitted` 计数。 |
| `list_valves` | `list_components` 的只读预设，类固定为阀门（`classes=["valve"]）。任何提供的 `classes` 参数都被覆盖。剩余的过滤器（`line`、`spec`、`size`、`limit`）和输出格式与 `list_components` 相同。 |
| `list_instruments` | `list_components` 的只读预设，类固定为仪器（`classes=["instrument"]`，映射到 `PartCategory="Instruments"`）。任何提供的 `classes` 参数都被覆盖。剩余的过滤器（`line`、`spec`、`size`、`limit`）和输出格式与 `list_components` 相同。 |
| `bom` | 物料清单：聚合 `list_components` 输出，按 **（类、规格、尺寸、描述）** 分组；每个不同组合成为一个 BOM 行，其 `quantity`（组件数量，不计算长度）。接受与 `list_components` 相同的范围过滤器（`classes`、`line`、`spec`、`size`、`limit`）。输出：`{ok, project, path, limit, filters, total_components, line_count, omitted, by_class, bom, notes}`；每个 BOM 行：`{class, spec, size, description, quantity}`。问题不属于它自己的 SQL - 只读聚合 `PipeRunComponent ⨝ EngineeringItems`。 |
| `pipe_length` | 真实管道长度 - 读取 `Pipe` 表（`Length` 列，单位来自 `LengthUnit`）连接到 `PipeRunComponent` 和 `EngineeringItems`；仅 `PartCategory='Pipe'` 行。按 `group_by` 分组（默认线路 \| `"spec"` \| `"size"` \| `"material"`）。范围过滤器：`line`、`spec`、`size`（`{"value","unit"}`）、`limit`（默认 50，0 = 无限制；限制组，报告 `omitted`）。未标记的管道始终显示在 `untagged` 字段中。输出：`{ok, project, path, limit, group_by, filters, length_unit, total_pipe_count, total_length, untagged, group_count, omitted, groups[], notes}`；每个组：`{group, pipe_count, length, length_unit}`。长度四舍五入到 2 位小数。 |
| `weld_list` | 焊接计数和分解 - 查询三个专用焊接表（`Buttweld`、`Socketweld`、`TapWeld`）；焊接子类型来自源表。每个焊接都连接到 `EngineeringItems`（直径/规格）和线路通过 `P3dLineGroupPartRelationship` → `P3dLineGroup.Tag` (~97% 覆盖率）。`Shop_Field` 被填充（SHOP/FIELD）→ 按照 shop-vs-field 始终存在。 `WeldNumber` 是 100% NULL（尚未分配的等长编号工具）。工具计数和分解，`group_by`（`"line"`| `"size"` \| `"spec"` \| `"shop_field"` \| `"type"`）。接受过滤器 `line`、`spec`、`size`、`shop_field`、`weld_type`、`limit`。未标记的焊接显示在 `untagged` 字段中。输出：`{ok, project, path, limit, group_by, filters, total_welds, by_type[], by_shop_field[], untagged{weld_count}, group_count, omitted, groups[], notes}`。`by_type` 和 `by_shop_field` 为全局分解（按降序）。焊接无有效线路显示在 `untagged` 中。当 `group_by="line"` 时，也显示为组 `"(SIN LÍNEA)"`。如果三个表格、`Shop_Field` 或线路关系表格/列缺失，则会优雅地降级。 |
| `bolt_gasket_list` | 螺栓和垫圈列表（法兰组件材料）- 查询 `Piping.dcf` 中的两个专用表：`BoltSet`（螺栓集；列 `BoltSize`、`NumberInSet`、`BoltCompatibleStd`、`Shop_Field`）和 `Gasket`。忽略通用 `Fasteners` 表（不可靠）。每个项目都连接到 `EngineeringItems`（规格、NominalDiameter/NominalUnit - 法兰直径，in/mm，非崩溃；材料）和线路通过 `P3dLineGroupPartRelationship` → `P3dLineGroup.Tag` (~80% 覆盖率；~20% 未标记是合法的分支头法兰）。双重数量指标：`item_count`（行：集合 + 垫圈）、`bolt_sets`、`individual_bolts`（Σ `NumberInSet`，从文本解析并作为 int 暴露；非数字 `NumberInSet` → 0 并附带注释）、`gaskets`（每个垫圈 = 1）。参数：`group_by`（默认线路 \| `"size"` \| `"spec"` \| `"material"` \| `"item_type"` \| `"shop_field"` \| `"bolt_size"`）。过滤器 `item_type`（`"bolt"` \| `"gasket"`）、线路、规格、尺寸（`{"value","unit"}`）、`shop_field`（`"shop"` \| `"field"`）、限制（默认 50，0 = 无限制；限制组，报告 `omitted`）。输出：`{ok, project, path, limit, group_by, filters, totals{item_count, bolt_sets, individual_bolts, gaskets}, by_item_type[], by_shop_field[], untagged{...}, group_count, omitted, groups[], notes}`。`by_item_type` 和 `by_shop_field` 为全局分解。无有效线路的项目显示在 `untagged` 中，当 `group_by="line"` 时，也显示为组 `"(SIN LÍNEA)"`。如果 `BoltSet`/`Gasket` 表、专用列（`NumberInSet`、`BoltSize`、`Shop_Field`）或线路关系表/列缺失，则会优雅地降级。 |
> 这些操作读取 Plant 3D 项目数据库（`.dcf` SQLite 文件）和规格目录（`Spec Sheets\*.pspc`，也是 SQLite），**只读**。它们 **不要求 .NET 插件或 AutoCAD 会话** - 除了 `detect_project`，它从活动绘图中读取 `DWGPREFIX`，如果未提供项目路径。`plant3d` 工具 **永远不会修改项目**。
> 设置可选环境变量 `AUTOCAD_MCP_PLANT3D_ROOT` 到一个包含 Plant 3D 项目子文件夹的文件夹；这允许 `list_projects` 和 `detect_project` 按名称而不是完整路径解析项目。
## 架构
```
MCP 客户端（Claude）
│ stdio (JSON-RPC)
▼
Python MCP 服务器（autocad_mcp）
│
├── 文件 IPC 后端 ──► C:/temp/*.json ──► mcp_dispatch.lsp (AutoCAD LT)
│ PostMessageW(WM_CHAR) 到 MDIClient - 无焦点偷取
│
└── ezdxf 后端 ──► 内存 DXF（无头，无需 AutoCAD）
```
## 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `AUTOCAD_MCP_BACKEND` | `auto` | 后端选择：`auto`、`file_ipc`、`ezdxf` |
| `AUTOCAD_MCP_IPC_DIR` | `C:/temp` | IPC 命令/结果 JSON 文件的目录（必须在 Python 和 LISP 双方匹配） |
| `AUTOCAD_MCP_IPC_TIMEOUT` | `10.0` | IPC 命令超时，单位：秒（1-300） |
| `AUTOCAD_MCP_ONLY_TEXT` | `false` | 禁用截图捕获（仅文本反馈） |
| `AUTOCAD_MCP_PLANT3D_ROOT` | | 可选的根文件夹，包含 Plant 3D 项目子文件夹；允许 `plant3d` 工具按名称而不是完整路径解析项目。 |
> **注意：** 如果您更改 `AUTOCAD_MCP_IPC_DIR`，您还必须更新 `*mcp-ipc-dir*` 变量 `mcp_dispatch.lsp` 以匹配。
## 开发
```powershell
uv sync
uv run pytest tests/ -v
```
## AutoCAD LT AutoLISP 兼容性
AutoLISP 在 AutoCAD LT 2024 版本中添加（仅限 Windows）。AutoCAD LT for Mac **不支持** AutoLISP。
| 支持（LT 2024+ Windows） | 不支持 |
|-------------------------------|---------------|
| `.lsp` / `.fas` / `.vlx` / `.dcl` | VLIDE（Visual LISP IDE） |
| 所有 `vl-*` 实用程序 | `vlax-*`（ActiveX/COM） |
| 文件 I/O (`open`, `read-line`, 等） | 快速工具 |
| 实体访问 (`entget`, `entmod`, 等） | 3D 操作 |
| 选择集 | AutoLISP 在 Mac 上 |
`mcp_dispatch.lsp` 分发器与 LT 2024+ 完全兼容。
## 新增 - Plant 3D 查询工具
`plant3d` 工具直接从项目 SQLite 数据库读取 AutoCAD Plant 3D 项目，无需 .NET 插件和 AutoCAD 会话：
- **`find_untagged`** - 识别无有效 `LineNumberTag` 的管道组件，按类和规格分解。
- **`validate_specs`** - 四项规格一致性检查（规格与所需规格、线路规格混合、空白规格、材料/日程安排在目录外）。
- **`list_lines`** - 生成项目线路列表（服务、规格、尺寸、绝缘、模型 DWG），使用 `P3dLineGroup` + `EngineeringItems` 的混合查询。
- **`list_components`** - 通用管道组件列表，支持按类、线路、规格和尺寸的可选过滤器；包括 `by_class` 分解和 `omitted` 计数。
- **`list_valves`** - 读取 `list_components` 的只读预设，类固定为阀门；与 `list_components` 相同过滤器和输出。
- **`list_instruments`** - 读取 `list_components` 的只读预设，类固定为仪器；与 `list_components` 相同过滤器和输出。
- **`bom`** - 物料清单：按（类、规格、尺寸、描述）聚合 `list_components`，返回一个 BOM 行，每个不同组合对应一个 `quantity`（组件数量）。接受与 `list_components` 相同的范围过滤器（`classes`、`line`、`spec`、`size`、`limit`）。
- **`pipe_length`** - 读取 `Pipe` 表的实际管道长度（`Length` 列，单位来自 `LengthUnit`），按线路/规格/尺寸分组。未标记的管道始终在 `untagged` 字段中显示。接受过滤器 `line`、`spec`、`size`、`limit`。
- **`weld_list`** - 从 `Buttweld`、`Socketweld` 和 `TapWeld` 表中查询焊接计数和分解；焊接子类型来自源表，线路通过 `P3dLineGroupPartRelationship` 解析。Shop-vs-field 分解始终存在（`Shop_Field` 填充）。按 `group_by` 分组（默认线路 \| `"size"` \| `"spec"` \| `"shop_field"` \| `"type"`）。接受过滤器 `line`、`spec`、`size`、`shop_field`、`weld_type`、`limit`。未标记的焊接显示在 `untagged` 字段中。
- **`bolt_gasket_list`** - 从 `BoltSet` 和 `Gasket` 表中查询螺栓和垫圈列表（法兰组件材料）。线路通过 `P3dLineGroupPartRelationship` 解析 (~80% 覆盖率)。双重数量指标：`bolt_sets`、`individual_bolts`（Σ `NumberInSet`）、`gaskets`（每个垫圈 = 1）。按 `group_by` 分组（默认线路 \| `"size"` \| `"spec"` \| `"material"` \| `"item_type"` \| `"shop_field"` \| `"bolt_size"`）。接受过滤器 `item_type`、`line`、`spec`、`size`、`shop_field`、`limit`。全局分解 `by_item_type` 和 `by_shop_field` 始终存在。未标记的项目显示在 `untagged` 字段中。
所有操作均打开 `.dcf` 和 `.pspc` 文件，模式为 `mode=ro`，从不写回项目。
## 新增 v3.1 中的功能
- **`execute_lisp`** - 通过临时文件模式运行任意 AutoLISP 代码。 将服务器从固定命令集转变为可扩展的自动化平台。
- **撤销/重做** - 通过 `drawing` 工具进行单步撤销和重做。
- **绘图打开** - 以编程方式打开现有的 `.dwg` 文件（FILEDIA 禁用）。
- **绘图创建** - 现在重置当前绘图（擦除所有内容 + 清除）而不是 `_。NEW`，保留 LISP 分发器命名空间。
- **绘图保存带路径** - `save` 带有 `path` 参数时使用 SAVEAS；无路径时使用 QSAVE。
- **`get_variables` 修复** - 尊重 `names` 参数；返回请求的变量并正确处理类型。
- **多边形/引线修复** - 正确编码的点数组通过分号分隔格式。
- **ESC 前缀** - 在每个调度之前发送 2x ESC 以取消超时之前的挂起命令。
- **UTF-8/cp1252 回退** - 处理 AutoCAD 写入的 LISP 结果文件中的非 ASCII 字符（AutoCAD 编写为 Windows-1252）。
- **可配置的 IPC 超时** - `AUTOCAD_MCP_IPC_TIMEOUT` 环境变量（1-300 秒，默认 10）。
- **线程安全的后端初始化** - `asyncio.Lock` 防止并行初始化竞争。
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器