Acad Cmd

acad cmd（AutoCAD MCP服务器）

本地MCP服务器（stdio/JSON-RPC），通过COM（pywin32）连接到Windows上的AutoCAD，并将命令行I/O作为MCP工具公开。

它的作用：

• 将文本发送到AutoCAD命令行(SendCommand)
• 打开DWG文件并将活动AutoCAD上下文切换到打开的图形
• 通过AutoCAD使用持久的完整命令历史记录 LOGFILEMODE / LOGFILENAME （主要输出源）
• 可选择阅读 LASTPROMPT 为了传统兼容性
• 可选使用进程内 .NET 事件桥(AcadEventBridge)用于结构化命令/文档生命周期事件
• 使用事件优先完成等待（自动回退到COM空闲等待）
• 为每个工具调用编写审计日志（JSONL）

需求

• 视窗
• AutoCAD（主要使用AutoCAD 2021进行测试；其他版本可能适用）
• Python 3.10+

兼容性（当前基线）

安装

py -3.11 -m venv .venv
.venv\Scripts\activate
pip install .

如果你的 python 命令打开Microsoft应用商店，使用 py -3.11 如上所述。

运行（独立）

建议先启动AutoCAD（也是最可靠的），然后：

acad-cmd

或者使用提供的辅助脚本（创建 .venv 并在首次运行时安装）：

start_server.bat

如果希望服务器启动AutoCAD，请设置 AUTOCAD_MCP_ACAD_EXE 到完整路径 到 acad.exe （服务器将启动该进程，然后通过COM连接）。

如果您安装/运行了多个Autodesk产品（例如Civil 3D和AutoCAD） 并且要强制使用特定的AutoCAD专业，请设置 AUTOCAD_MCP_TARGET_MAJOR.

示例：AutoCAD 2021是主要的 24:

set AUTOCAD_MCP_TARGET_MAJOR=24

重要连接行为：

• 通过COM发现AutoCAD实例（第一个 GetActiveObject，然后可选 Dispatch).
• 某些安装不会将正常启动的UI实例暴露给 GetActiveObject.

在这种情况下， Dispatch 可以附加到正在运行的实例或生成新的启用自动化的实例。

• 要禁用生成新AutoCAD实例，请设置 AUTOCAD_MCP_ALLOW_NEW_INSTANCE=0.
• 如果要附加正常启动的UI实例，请在启用自动化的情况下启动AutoCAD

（通常 acad.exe /automation，但这可能因安装而异）。

运行时日志写在 logs/acad-cmd//.

事件桥（可选）

acad-cmd 可以使用进程内AutoCAD插件(AcadEventBridge)结构化事件的管道名称过多。

• 命令/lisp完成可以从事件流中解析出来（比纯文本检查更快、更确定）
• 文档生命周期事件在状态/诊断中可用
• 如果网桥不可用或降级，服务器将自动回退到旧的COM空闲等待和日志文件路径

插件源代码和冒烟命令位于 plugins/AcadEventBridge/README.md.

配置（环境变量）

连接/版本选择：

• AUTOCAD_MCP_TARGET_MAJOR （可选）：固定AutoCAD主要版本（例如。 24 适用于AutoCAD 2021）。
• AUTOCAD_MCP_ALLOW_NEW_INSTANCE （默认：允许）：设置为 0 防止产生新的 acad.exe 通过COM激活。
• AUTOCAD_MCP_USE_DISPATCH （默认设置：关闭，除非 AUTOCAD_MCP_TARGET_MAJOR 已设置）：强制尝试 Dispatch 激活。
• AUTOCAD_MCP_PREFER_CURVER （默认：关闭）：首选注册表 CurVer 解析AutoCAD版本时的ProgID。
• AUTOCAD_MCP_EVENT_BRIDGE_ENABLED （默认值： 0)：启用桥接集成路径。

事件桥行为：

• AUTOCAD_MCP_EVENT_BRIDGE_HEARTBEAT_TIMEOUT_SEC （默认值： 6.0)：桥接等待的心跳新鲜度阈值。
• AUTOCAD_MCP_EVENT_BRIDGE_MAX_DROPPED_FOR_WAIT （默认值： 0)：在降级为回退等待之前，最大容忍丢弃队列消息。
• AUTOCAD_MCP_EVENT_BRIDGE_OBJECT_EVENTS_ENABLED （默认值： 1)：所需的插件端对象事件模式(AEB_OBJECT_EVENTS_ON/OFF 同步）。
• AUTOCAD_MCP_EVENT_BRIDGE_AUTOLOAD （默认值： 1)：启用网桥时，允许尽力而为的插件自动加载(NETLOAD)如果管道不可用。
• AUTOCAD_MCP_EVENT_BRIDGE_AUTOLOAD_DLL （可选）：显式路径 AcadEventBridge.dll 用于自动加载；否则，服务器将尝试默认的构建位置。

启动AutoCAD：

• AUTOCAD_MCP_ACAD_EXE （可选）：完整路径 acad.exe 显式启动AutoCAD。
• AUTOCAD_MCP_ACAD_ARGS （可选）：传递给的额外参数 acad.exe 发射时。
• AUTOCAD_MCP_LAUNCH_WAIT_SEC （默认值： 30)：在重试COM附着之前，等待AutoCAD启动需要多长时间。

Claude桌面配置示例

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "acad-cmd": {
      "command": "C:/path/to/project/.venv/Scripts/python.exe",
      "args": ["-m", "acad_cmd.server"]
    }
  }
}

笔记：

• .venv 未提交到git，克隆后不会出现；在本地创建（或运行 start_server.bat).
• 如果希望服务器自动启动AutoCAD，请设置 AUTOCAD_MCP_ACAD_EXE 到完整的路径 acad.exe.

工具

所有工具都返回JSON（FastMCP通常将结果包装为 { "result": ... }).

• get_status()

- 返回连接信息（DWG标签， ACADVER，窗口句柄/PID（如果可用）和默认流详细信息 - 包括繁忙/降级状态的稳定性字段： busy, stale, source, error_class, cmdactive - 包含绑定信息以避免跨版本漂移： locked_major, bound_progid - 包括 event_bridge 诊断：可用性/连接性、管道/插件元数据、心跳/队列状态、降级原因和可选服务状态

• send_command(command, timeout_sec, wait=true, poll_interval_sec=0.1)

- 发送原始命令行文本 - 当 wait=true：在可用时使用网桥事件优先完成等待，否则回退到COM空闲等待 - 确保默认日志文件流，并返回 log 带有新输出和更新光标的块 - 返回等待诊断(wait_source, wait_completion_event, wait_completion_seq, wait_fallback_used, bridge_wait_prepare_issue)

• open_drawing(path, timeout_sec, read_only=false)

- 打开DWG并保证主动切换到目标文档（或超时时出错） - 回报 dwg_before, dwg, already_open, opened, activated

• get_last_output(source=lastprompt|logfile)

- 默认源为 logfile - logfile：返回当前默认日志文件流的尾部（如果需要，会自动启动日志文件流） - lastprompt：阅读 LASTPROMPT （传统/回退源）

• start_logging(mode=logfile|lastprompt, logfile_path=null, reset=false)

- 启动流并返回 {stream_id, cursor, ...} - logfile 模式启用 LOGFILEMODE 和轨道 LOGFILENAME - lastprompt 模式仅用于向后兼容性 - 如果 logfile_path 如果未提供，服务器将首选AutoCAD的当前版本 LOGFILENAME 避免路径问题

• get_new_output_since(stream_id, cursor, max_bytes=65536)

- 读取附加的日志文件字节并返回 {text, new_cursor, truncated}

• stop_logging(stream_id)

- 阻止溪流；尽力禁用 LOGFILEMODE 当最后一个服务器启动的日志文件流停止时

• load_lisp_file(path, timeout_sec, wait=true)

- 发送 (load "...") （AutoCAD的路径标准化） - 当 wait=true：首先使用网桥LISP完成事件，然后在需要时使用COM回退

• run_lisp(expr, timeout_sec, wait=true)

- 通过执行AutoLISP表达式/脚本 SendCommand 命令历史记录中有开始/结束标记 - 当 wait=true：首先使用网桥LISP完成事件，然后在需要时使用COM回退

• selection(timeout_sec, prompt=null, filter=null, max_objects=null, alert_message=null)

- 返回当前选定的对象（PickFirst）；如果没有，则提示用户选择对象 - 当 alert_message 提供，需要交互式选择，显示标准AutoCAD alert - 仅返回 handle + type 对于每个对象

• dict_list/dict_keys/dict_xrecord_get/dict_xrecord_set/dict_xrecord_delete/dict_delete(..., timeout_sec)

- 字典工具现在需要显式 timeout_sec 也 - 所有等待工具的超时范围： 0.1..1800 秒

故障排除说明

• AutoCAD安全设置可以阻止加载AutoLISP文件。

- 添加您的文件夹 .lsp 文件到AutoCAD 信任位置. - 检查 SECURELOAD 行为（不要削弱全球生产安全）。

• 如果COM调用失败并显示“被呼叫者忙”，则服务器将通过回退重试。
• LOGFILEMODE/LOGFILENAME 在AutoCAD的当前代码页中写入文件；解码使用您的Windows首选编码和回退。

开发/烟雾测试

• scripts/mcp_smoketest_stdio.py：通过stdio生成服务器，列出工具，开始日志记录，运行一个小的LISP表达式。
• scripts/mcp_sanity_acadver.py：直接COM健全性检查 LOGFILEMODE 发送后输出增长 (getvar 'ACADVER).
• scripts/mcp_baseline_capture.py：路线图步骤1基线捕获(get_status, send_command, run_lisp, LOGFILEMODE)使用JSON报告 out/baseline/.

运行单元测试：

python -m unittest discover -s tests -p "test_*.py"

运行集成测试（需要真正的AutoCAD）：

set ACAD_MCP_RUN_INTEGRATION=1
python -m unittest discover -s tests -p "test_*.py"

存储库文档

• 贡献指南： CONTRIBUTING.md
• 安全策略： SECURITY.md
• 许可证： LICENSE