内容
# AutoCAD MCP 服务器
用于 Windows 上 AutoCAD 的生产级模型上下文协议（MCP）服务器，使 AI 助手（Claude Desktop、ChatGPT、Cursor 等）能够通过自然语言控制 AutoCAD。
## 功能
- **10 种全面的 MCP 工具** 用于 CAD 操作
- **AutoCAD COM API 集成** 用于原生 Windows 自动化
- **自然语言控制** - “绘制一个 100x50 的矩形” → 创建几何图形
- **自动连接管理** 带有重新连接逻辑
- **完整的类型提示和 Pydantic 验证** 用于安全
- **生产日志** 用于调试和监控
- **单元测试** 覆盖所有工具和边缘情况
- **快速且轻量级** 使用 FastMCP 框架
## 技术栈
- Python 3.11+
- [FastMCP](https://github.com/janus-ai/fastmcp) - MCP 框架
- [pyautocad](https://pypi.org/project/pyautocad/) - AutoCAD COM 包装器
- [pywin32](https://github.com/pywin32) - Windows COM 支持
- [Pydantic](https://docs.pydantic.dev/) - 数据验证
- [uv](https://github.com/astral-sh/uv) - 快速 Python 包管理器
## 可用工具
### 绘图工具
1. **create_line** - 在两个点之间绘制一条线
- 参数：`x1`、`y1`、`x2`、`y2`
- 返回：创建的线对象的 ID
2. **create_circle** - 绘制一个圆
- 参数：`center_x`、`center_y`、`radius`
- 返回：创建的圆对象的 ID
3. **create_rectangle** - 绘制一个矩形
- 参数：`x`、`y`、`width`、`height`
- 返回：对象 ID 列表（折线 + 实体）
4. **create_text** - 添加文本注释
- 参数：`text`、`x`、`y`、`height`
- 返回：创建的文本对象的 ID
### 图层管理
5. **create_layer** - 创建一个新图层
- 参数：`layer_name`
- 返回：图层名称（或如果存在则返回错误）
6. **list_layers** - 列出文档中的所有图层
- 无参数
- 返回：图层名称列表
### 分析和测量
7. **calculate_area** - 计算封闭形状的面积
- 参数：`object_id`
- 返回：计算的面积值
### 文档操作
8. **save_drawing** - 保存活动绘图
- 参数：`file_path`（可选，默认为当前）
- 返回：带有文件路径的成功消息
9. **export_pdf** - 将绘图导出为 PDF
- 参数：`output_path`
- 返回：带有 PDF 路径的成功消息
10. **get_active_document** - 获取活动文档信息
- 无参数
- 返回：文档名称和完整路径
## 安装
### 先决条件
- **Windows 10/11** （AutoCAD COM API 仅限 Windows）
- **AutoCAD 2020+** 已安装并正在运行
- **Python 3.11+** 带有 pip
- **uv** 包管理器（推荐）
### 步骤 1：克隆存储库
```bash
git clone https://github.com/yourusername/autocad-mcp-server.git
cd autocad-mcp-server
```
### 步骤 2：安装依赖项
使用 **uv** （最快）：
```bash
uv sync
```
或使用 **pip**：
```bash
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
```
### 步骤 3：安装 pywin32 COM 支持
安装 pywin32 后，注册 COM 组件：
```bash
python -m pip install --upgrade pywin32
python Scripts/pywin32_postinstall.py -install
```
或如果使用 uv：
```bash
uv run python -m pip install --upgrade pywin32
uv run python Scripts/pywin32_postinstall.py -install
```
### 步骤 4：验证安装
```bash
# 测试 AutoCAD COM 是否可访问
python -c "import win32com.client; acad = win32com.client.GetObject(class='AutoCAD.Application'); print(f'AutoCAD {acad.Version} detected')"
```
## AutoCAD 先决条件
### 1. AutoCAD 必须正在运行
服务器通过 COM 连接到正在运行的 AutoCAD 实例：
```bash
# 在运行 MCP 服务器之前启动 AutoCAD
# AutoCAD 将在后台运行
```
### 2. 启用 COM 自动化（通常为默认值）
AutoCAD COM 默认启用。要验证：
1. 打开 AutoCAD
2. 转到 **工具** → **选项** → **系统**
3. 确保“OLE 支持”已**启用**
### 3. AutoCAD COM 版本支持
| AutoCAD 版本 | COM 版本 | Python 支持 |
|---|---|---|
| 2024 | 24.x | ✅ 是 |
| 2023 | 23.x | ✅ 是 |
| 2022 | 22.x | ✅ 是 |
| 2021 | 21.x | ✅ 是 |
| 2020 | 20.x | ✅ 是 |
## 配置
### 环境变量
创建一个 `.env` 文件（从 `.env.example` 复制）：
```env
# AutoCAD 连接超时（秒）
AUTOCAD_TIMEOUT=10
# 连接重试尝试次数
RETRY_ATTEMPTS=3
# 日志级别：DEBUG、INFO、WARNING、ERROR
LOG_LEVEL=INFO
# 服务器主机和端口
MCP_HOST=127.0.0.1
MCP_PORT=8000
```
## 用法
### 选项 1：作为独立 MCP 服务器运行
```bash
# 终端 1：启动 AutoCAD（如果尚未运行）
# 手动打开 AutoCAD
# 终端 2：启动 MCP 服务器
python -m src.server
```
服务器将：
- 检测正在运行的 AutoCAD 实例
- 使用 MCP 注册所有工具
- 监听工具调用
- 如果 AutoCAD 重启，则重新连接
### 选项 2：Claude Desktop 集成
#### 步骤 1：获取服务器 URL
在本地运行时，服务器可在以下位置访问：
```
stdio://python -m src.server
```
#### 步骤 2：配置 Claude Desktop
编辑 `~/.config/Claude/claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"autocad": {
"command": "python",
"args": ["-m", "src.server"],
"cwd": "d:/autocad-mcp-server"
}
}
}
```
在 Windows 上，配置文件位于：
```
C:\Users\[YourUsername]\AppData\Roaming\Claude\claude_desktop_config.json
```
#### 步骤 3：重启 Claude Desktop
关闭并重新打开 Claude Desktop。AutoCAD 工具将出现在工具部分。
### 选项 3：ChatGPT 自定义操作
使用指向正在运行的 MCP 服务器的架构创建 ChatGPT 自定义操作。
### 选项 4：Cursor IDE 集成
在 Cursor 设置中，配置 MCP 服务器端点：
```json
{
"mcpServers": {
"autocad": {
"command": "python",
"args": ["-m", "src.server"]
}
}
}
```
## 示例提示
连接后，使用自然语言控制 AutoCAD：
### 基本绘图
- “绘制一条从 (0, 0) 到 (100, 50) 的线”
→ 调用 `create_line` 并带有坐标
- “在中心 (50, 50) 处创建一个半径为 25 的圆”
→ 调用 `create_circle`
- “在原点处绘制一个 100x50 的矩形”
→ 调用 `create_rectangle`
### 文本和注释
- “在坐标 (10, 20) 处添加文本 'WALL-A'，高度为 5”
→ 调用 `create_text`
### 图层管理
- “创建一个名为 'Fixtures' 的新图层”
→ 调用 `create_layer`
- “显示我绘图中的所有图层”
→ 调用 `list_layers`
### 分析
- “计算 ID 为 'ABC123' 的对象的面积”
→ 调用 `calculate_area`
### 文档管理
- “保存绘图”
→ 调用 `save_drawing`
- “将绘图导出到 C:\output\plan.pdf”
→ 调用 `export_pdf`
- “活动文档的名称是什么？”
→ 调用 `get_active_document`
## 故障排除
### 问题：”AutoCAD 未找到” 或连接被拒绝
**解决方案：**
1. 在启动 MCP 服务器之前手动打开 AutoCAD
2. 验证 AutoCAD 是否正在运行：任务管理器 → 搜索“acad”
3. 检查 AutoCAD 版本是否支持 COM（2020+）
```bash
# 调试：测试 COM 访问
python -c "from src.autocad_client import AutoCADClient; c = AutoCADClient(); print(c.get_document_info())"
```
### 问题：”模块未找到” 错误
**解决方案：
```bash
# 重新安装依赖项
pip install -r requirements.txt
# 或使用 uv
uv sync --reinstall
```
### 问题：pywin32 COM 未注册
**解决方案：
```bash
python -m pip install --upgrade pywin32
python Scripts/pywin32_postinstall.py -install
# 在某些系统上，以管理员身份运行
```
### 问题：保存文件时出现“权限被拒绝”
**解决方案：
1. 确保输出目录存在且可写入
2. 如果需要，以管理员身份运行 AutoCAD
3. 检查文件路径是否使用正斜杠或双反斜杠：
```python
# 良好的做法
"C:/output/drawing.pdf"
"C:\\output\\drawing.pdf"
# 不佳的做法
"C:\output\drawing.pdf" # 单反斜杠被解释为转义码
```
### 问题：MCP 服务器无法启动
**解决方案：
1. 检查 Python 版本：`python --version`（应为 3.11+）
2. 验证依赖项：`pip list | grep -E "fastmcp|pyautocad|pydantic"`
3. 检查日志：
```bash
# 以 DEBUG 日志级别运行
LOG_LEVEL=DEBUG python -m src.server
```
### 问题：Claude Desktop 中工具未显示
**解决方案：
1. 验证配置文件是否存在：`C:\Users\[You]\AppData\Roaming\Claude\claude_desktop_config.json`
2. 检查 JSON 语法是否有效（使用 [jsonlint.com](https://jsonlint.com)）
3. 完全重启 Claude Desktop
4. 检查服务器日志中的启动错误
### 问题：AutoCAD 崩溃或无响应
**解决方案：
1. 服务器包含超时和错误处理
2. 如果 AutoCAD 冻结，请终止进程并重启
3. 服务器将在 AutoCAD 重启时自动重新连接
4. 检查不支持的 AutoCAD 操作（例如复杂几何）
## 测试
运行单元测试套件：
```bash
# 运行所有测试
pytest
# 运行覆盖测试
pytest --cov=src
# 运行特定测试文件
pytest tests/test_models.py
# 运行详细输出
pytest -v
```
测试覆盖范围包括：
- ✅ Pydantic 模型验证
- ✅ 工具参数验证
- ✅ AutoCAD 连接逻辑
- ✅ API 端点功能
- ✅ 错误处理和边缘情况
## 项目结构
```
autocad-mcp-server/
├── src/
│ ├── __init__.py
│ ├── server.py # MCP 服务器入口点
│ ├── autocad_client.py # AutoCAD COM 包装器
│ ├── models.py # Pydantic 验证模型
│ └── tools/
│ ├── __init__.py # 工具注册
│ ├── drawing.py # 线、圆、矩形、文本
│ ├── layers.py # 图层管理
│ ├── dimensions.py # 面积计算
│ └── export.py # 保存和 PDF 导出
├── tests/
│ ├── test_models.py # 模型验证测试
│ ├── test_server.py # API 端点测试
│ └── test_tools.py # 工具处理程序测试
├── pyproject.toml # uv/pip 依赖项
├── .env.example # 环境模板
└── README.md # 本文件
```
## 架构
### AutoCAD 连接
```
┌─────────────────────────────────────────┐
│ Claude Desktop / ChatGPT / etc │
└──────────────────┬──────────────────────┘
│
│ （MCP 协议）
│
┌──────────────────▼──────────────────────┐
│ MCP 服务器 (FastMCP) │
│ ├─ 工具注册 │
│ ├─ 请求调度器 │
│ └─ Pydantic 验证器 │
└──────────────────┬──────────────────────┘
│
│ （Python API）
│
┌──────────────────▼──────────────────────┐
│ AutoCAD 客户端 (pyautocad) │
│ ├─ 连接管理器 │
│ ├─ 重试逻辑 │
│ └─ 错误处理器 │
└──────────────────┬──────────────────────┘
│
│ （COM 自动化）
│
┌──────────────────▼──────────────────────┐
│ AutoCAD 应用程序 (COM) │
│ ├─ 绘图 API │
│ ├─ 图层管理 │
│ └─ 文档操作 │
└─────────────────────────────────────────┘
```
## 性能说明
- **快速** - 直接 COM 调用，无网络开销
- **轻量级** - 依赖项最小
- **可靠** - AutoCAD 重启时自动重新连接
- **安全** - 具有 Pydantic 模型的完整输入验证
- **并发** - 处理多个 AI 助手请求
## 安全考虑
- ✅ 在 Windows 上本地运行（无云暴露）
- ✅ 所有工具参数的输入验证
- ✅ 使用 Pydantic 模型类型安全
- ✅ 错误处理防止信息泄露
- ⚠️ AutoCAD 文件访问 - 确保适当的文件权限
- ⚠️ 通过网络公开时，使用身份验证/TLS
## 贡献
欢迎拉取请求！ 增强领域：
- [ ] 额外的绘图基元（弧，折线，样条曲线）
- [ ] 块/组件支持
- [ ] 尺寸注释
- [ ] 填充图案
- [ ] 自定义属性
- [ ] 多文档支持
- [ ] CAM 集成
- [ ] 版本控制以更改绘图
## 许可证
MIT - 请参阅 LICENSE 文件
## 支持
- 📧 **问题：** GitHub 问题
- 💬 **讨论：** GitHub 讨论
- 📚 **文档：** [AutoCAD COM API 参考](https://help.autodesk.com/view/OARX/2024/ENU/)
- 🔗 **MCP 协议：** [模型上下文协议规范](https://spec.modelcontextprotocol.io)
## 更新日志
### v1.0.0（2026-06-05）
- 初始发布
- 10 个核心 CAD 工具
- Claude Desktop 集成
- 完整的测试覆盖
- 生产就绪代码
## 路线图
- [ ] AutoCAD Web API 支持云部署
- [ ] 使用 WebSocket 实现实时绘图更新
- [ ] 高级几何操作（偏移，修剪，延伸）
- [ ] 材料/属性管理
- [ ] CAM 集成
- [ ] 版本控制以更改绘图
---
**使用 ❤️ 为 AI 驱动的 CAD 自动化而创建**
