# AutoCAD-mcp

> 用自然语言 / AI 驱动你电脑上正在运行的 **AutoCAD** 完成 2D 制图自动化。  
> 通过 MCP 协议把 AutoCAD 的绘图、标注、图层/块、机械图框/标题栏/BOM/球标等能力暴露给 WorkBuddy 及任意 MCP 客户端；支持 AutoCAD 2014 及兼容版本。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org)
![Release](https://img.shields.io/github/v/release/liqi82/autocad-mcp)

---

## 它能做什么

通过 Windows COM(ActiveX) 连接本机 AutoCAD，把以下能力以 **MCP 工具**暴露给 WorkBuddy / 任意 MCP 客户端：

- 🖊️ **绘制**：直线、圆、多段线、矩形、单行/多行文字
- 📐 **标注**：线性、对齐、半径、直径
- 🗂️ **图层 / 块 / 样式管理**：新建图层、切换当前层、块定义与插入、中文文字样式（宋体，不乱码）
- 📐 **机械制图**：A3 图框、GB 标准中文标题栏、BOM 明细表、球标
- 🔍 **查询 / 清理**：列出实体、按图层擦除、按 Handle 平移

## 能力清单（MCP 工具）

| 能力 | 对应工具 |
|---|---|
| 连接 / 环境探测 | `connect` / `capabilities` / `list_documents` |
| 绘制 线/圆/多段线/矩形/文字 | `draw_line` / `draw_circle` / `draw_polyline` / `draw_rect` / `add_text` / `add_mtext` |
| 查询图面 | `query_entities` |
| 标注 线性/对齐/半径/直径 | `dim_linear` / `dim_aligned` / `dim_radial` / `dim_diameter` |
| 图层 / 块 / 样式 | `ensure_layer` / `set_current_layer` / `ensure_block` / `insert_block` |
| 机械图框 / 标题栏 / BOM / 球标 | `a3_frame` / `title_block` / `bom_grid` / `balloon` |
| 清理 / 变换 | `erase_layer` / `move_entity` |

> 机械图框、GB 标准标题栏、BOM 明细表、球标等均以几何 + 文字直接生成，开箱即用、无需依赖任何 CAD 私有向导。

---

## 环境要求

- **Windows**（COM/ActiveX 仅 Windows 可用）
- **AutoCAD 已安装并打开至少一张 DWG**（2014 及兼容版本；理论上支持 R2010+ 的 ActiveX 接口）
- 运行环境：首次启动会自动拉取 `mcp`(v1) + `pywin32`

> ⚠️ 本连接器仅支持 **AutoCAD**，需要本机已安装并运行 AutoCAD（依赖 Windows COM/ActiveX）。

---

## 安装与运行

### 方式一：uvx / pipx（推荐，发布后）

```bash
uvx autocad-mcp            # 自动下载并启动 MCP 服务（stdio）
# 或
pipx run autocad-mcp
```

### 方式二：从源码

```bash
git clone https://github.com/liqi82/autocad-mcp.git
cd autocad-mcp
pip install -e .
autocad-mcp                # 或 python -m autocad_mcp.server
```

本地开发时也可直接进入 `src` 目录用托管 Python 运行：

```bash
cd autocad-mcp/src
python -m autocad_mcp.server
```

---

## 接入 WorkBuddy（连接器）

1. 把下面内容合并进 WorkBuddy 的 `~/.workbuddy/mcp.json` 的 `mcpServers`：

   ```json
   {
     "mcpServers": {
       "autocad-2d": {
         "command": "uvx",
         "args": ["autocad-mcp"],
         "env": { "PYTHONUTF8": "1" }
       }
     }
   }
   ```

2. 在连接器管理页面对 **「autocad-2d」** 点击 **信任 / 启用**。
3. 确认 AutoCAD 已打开一张 DWG。
4. 在对话里直接说，例如：*"在 Drawing2.dwg 画一个直径 300 的圆"*、*"插入 A3 图框并填写标题栏"*。

> 本地未发布时，可把 `command` 改为你的 Python 解释器、`args` 改为 `["-m","autocad_mcp.server"]`、`cwd` 指向 `src` 目录。

---

## 使用示例（MCP 工具直接调用）

```text
connect()                                  → 连接当前活动图纸，返回能力信息
a3_frame(landscape=true)                   → 插入 A3 横式外框
title_block(fields={"图名":"总布置图","图号":"SC-001","比例":"1:200"})
draw_circle(cx=210, cy=148.5, radius=150)  → 直径 300 的圆
bom_grid(origin_x=20, origin_y=360,
         headers=["序号","名称","数量","材料"],
         rows=[["1","船体","1","钢"],["2","电机","2","—"]],
         col_widths=[20,80,30,40])
balloon(x=120, y=200, number="1", leader_x=160, leader_y=230)
dim_linear(x1=0,y1=0,x2=420,y2=0,tx=210,ty=-15)   → 水平尺寸标注
query_entities()                            → 列出模型空间所有实体
erase_layer("HW_TEST_TMP")                  → 清理临时图层
```

---

## 快速演示（一键跑通全套能力）

仓库内置一个端到端演示脚本 `examples/demo_showcase.py`，它通过**真实 MCP stdio 服务器**在目标图纸上画出一张带标注的机械示例图（矩形轮廓 + 孔 + 线性标注 + 球标 + BOM 明细表 + 文字），全部画在独立图层 `HW_DEMO`，便于一键清理。

```bash
# 1) 先装好连接器（见上文「方式二：从源码」）
pip install -e .

# 2) 打开 AutoCAD 与目标图纸（默认 Drawing2.dwg，可在脚本顶部的 TARGET_DOC 改）
# 3) 运行演示（用托管 Python）
python examples/demo_showcase.py
```

演示会依次调用 `connect → ensure_layer → draw_rect → draw_circle → dim_linear → balloon → bom_grid → add_text`，并输出每个工具的返回值（Handle）。效果等价于你亲口说："在 Drawing2 画一个矩形零件，开个孔，标个尺寸，加球标和 BOM"。

> 想看真实渲染，直接用 AutoCAD 打开该图纸、切到 `HW_DEMO` 图层即可；清理时删除该图层内容或调用 `erase_layer(layer="HW_DEMO")`。

---

## 局限与注意事项

- **仅 Windows + AutoCAD**：依赖 COM/ActiveX，无法在 macOS/Linux 或非 AutoCAD 环境使用。
- **需 AutoCAD 运行中**：服务启动后通过 `GetActiveObject` 连接已运行的 AutoCAD 实例；未启动会报错。
- **单实例**：多开 AutoCAD 时可能连到非预期窗口，建议用 `connect(doc_name=...)` 显式指定。
- **中文**：文字默认使用 `HW_CN`（宋体 TTF）样式以避免方框乱码。
- **安全**：删除实体、保存、关闭文档等写操作请先确认；本服务只新增实体、不自动保存，便于 Ctrl+Z 撤销。

## FAQ

**Q：需要联网吗？**  
A：不需要。连接器完全在本机通过 COM 与已运行的 AutoCAD 通信，不上传你的图纸。

**Q：支持 AutoCAD 哪个版本？**  
A：ActiveX 接口自 R2010 起基本稳定，已在 AutoCAD 2014（19.1s 中文版）验证；更高版本通常也可用。

**Q：能画 3D 吗？**  
A：当前聚焦 2D 制图自动化。3D 可后续扩展。

**Q：坐标单位是什么？**  
A：当前图纸的单位（通常毫米）。角度为弧度。

---

## 发布与分享

本项目设计为可发布、可分享：

- **GitHub**：`git tag v0.1.0` 后发布 Release；`pyproject.toml` 已配置 `autocad-mcp` 控制台入口，可 `uvx autocad-mcp` 直接使用。
- **WorkBuddy 技能市场**：将本仓库的 `SKILL.md` 与 `src/` 按 WorkBuddy 技能/连接器规范打包上传，即可在「推荐市场」被发现与一键安装。
- **私有分发**：直接把整个文件夹发给同事，`pip install -e .` 后即可用。

欢迎提 Issue / PR，一起把 AutoCAD 自动化能力补全。

## License

[MIT](LICENSE) © 2026 John Zhang, ZWCAD-2D contributors, 李琦 (liqi8209@qq.com)

_author：李琦/liqi(Email: liqi8209@qq.com)_