live-chemdraw-mcp

live-chemdraw-mcp

一个 MCP 服务，通过 COM 自动化将 AI 助手连接到 Windows 上的实时 ChemDraw 窗口——直接在已打开的文档中绘制、编辑和整理结构。 功能：

• 插入与导出 — 支持 SMILES、名称、molfile、InChI、CDXML；可导出为图像、结构文本，或直接复制到剪贴板
• 底物范围表格 — 一次调用即可构建完整的范围图，尺寸适合期刊栏宽，并将标签／收率放在各结构下方
• 简写基团 — 在行内检测并缩写官能团 （chemdraw_contract_group：Ph、TES、Boc、Ts……约 40 种基团，通过 RDKit 进行 SMARTS 匹配），或将整个结构缩写／展开为单个标签；还支持一次调用即可批量展开整个文档
• 图形布局 — chemdraw_describe_canvas 可对整页进行一次语义读取（结构、与所属对象匹配的说明文字、面板框、重叠／溢出违规）；chemdraw_arrange_in_region 可在一次调用中将结构适配到面板框内，说明文字随之移动，且绝不重新缩放；chemdraw_get_layout／chemdraw_move_objects 可用于制定原始几何布局方案，并自动检测连带移动
• 化学质控 — 读取／设置立体化学（楔形／虚线键、“and1”／“or1”增强型立体化学分组）、重复项检测、价态警告、IUPAC 命名、生成 HRMS 文本
• 出版工具 — 期刊样式预设、反应方案，以及使用 RDKit 计算属性的衍生物库枚举
• 注释 — 机理／反应箭头（chemdraw_make_arrow：实心／空心／角形箭头、单倒刺“鱼钩”电子推动箭头、划掉的“不可行”路径标记、偶极标记）和符号 （chemdraw_make_symbol：外消旋／绝对／相对立体描述符标签；孤对电子／自由基／匕首符号也能放置，但目前渲染尺寸极小，且似乎无法缩放——参见工具自身的文档字符串）。 同位素标记（chemdraw_edit_atom(..., isotope=13, ...)）在导出时会保留为真实的同位素标记，而不只是 ChemDraw 显示标签。 限制： 箭头／符号是独立浮动对象——使用 chemdraw_move_objects／chemdraw_transform 移动附近结构时，它们不会随之移动；这与下文已记录的说明文字问题属于同一类缺陷。 目前不支持弧形／曲线箭头，也不支持真正的双对象 ⇌ 平衡箭头对——这两项都已进行实时探测，但在做出设计承诺前还需进一步调查 COM（参见 docs/com_typelib/）
• 聚合物重复单元括号（chemdraw_make_bracket：方形／花括号／圆括号字形；用于 SRU／单体／共聚物／交联……，并使用 ChemDraw 自动生成的缩写标签——“n”／“mon”／“xl”等）可用一对开括号与闭括号包围结构（或显式矩形）。 限制，已通过实时测试确认，尚未解决： 无法通过 COM 设置 RepeatCount／SRULabel／ComponentOrder（读取和写入都会稳定地报错）；同一自动化会话中出现第二个括号后，这一对括号的镜像方向（“[...]”与两个朝向相同的标记）并不可靠——务必检查导出的图像；括号纯属装饰（并未绑定真实的原子／键成员关系，尽管 ChemDraw 提供了 InsideAtoms／ContainedAtoms／CrossingBonds 属性——已确认这些属性不能反映真实几何位置），且与上文的箭头／符号一样，属于独立浮动对象，不会随结构移动
• TLC 板（chemdraw_make_tlc_plate：带标注 Rf 斑点泳道的矩形板框，用于反应监测图）——斑点的垂直位置完全由其 rf（0-1）属性决定；ChemDraw 会自行在板的原点线与溶剂前沿线之间进行插值（已通过测量屏幕截图中的像素位置实时确认，与预期比例相差约 1%），无需手动计算位置。支持 show_rf（自动生成“Rf = 0.NN”标签）、filled／bold／dashed（已通过视觉确认，空心虚线圆与实心圆点明显不同），以及实验性的 tail（彗尾状拖尾）；但在现有截图分辨率下无法确认其视觉效果。硬性限制，已通过实时测试确认并由工具强制执行（在任何 COM 调用之前报错）：单个泳道最多只能容纳 2 个斑点——超过此数量后，ChemDraw 自身的 AddSpot 会静默地不执行任何操作，且完全不报错。与上文的箭头／符号／括号一样，TLC 板也属于独立浮动对象，不会随结构移动。 本 README 介绍安装和使用方法，不是逐个工具的参考文档（每个工具的确切参数、返回格式和使用说明均位于各自的文档字符串中，任何 MCP 客户端都可以通过工具列表查看），也不介绍内部架构或 ChemDraw-COM 的实现细节（请参阅 AGENTS.md 了解这些内容。无论你是在调试、好奇它的工作原理，还是要扩展它，只要查看源代码，这份文档都值得一读，不只是最后一种情况）。

基于 ChemDraw 26（Revvity） 在 Windows 11 / Python 3.14 上构建并验证。

这是一个独立的非官方项目，与 Revvity 或 PerkinElmer 没有关联，也未获其认可或支持。“ChemDraw” 是其各自所有者的商标；此处仅用于说明兼容性。使用本项目需要你拥有 ChemDraw 的有效许可副本。

安装

cd live-chemdraw-mcp
python -m venv .venv
.venv\Scripts\python -m pip install pywin32 rdkit "mcp[cli]" pytest

在 %APPDATA%\Claude\claude_desktop_config.json 中注册（将 C:\\path\\to\\live-chemdraw-mcp 替换为你克隆项目的位置）：

"mcpServers": {
  "chemdraw": {
    "command": "C:\\path\\to\\live-chemdraw-mcp\\.venv\\Scripts\\python.exe",
    "args": ["C:\\path\\to\\live-chemdraw-mcp\\server.py"]
  }
}

重启 Claude 桌面应用。无需在 ChemDraw 端安装任何内容——MCP 服务会通过 COM 连接到正在运行的 ChemDraw（或启动一个实例）。

测试

• .venv\Scripts\python -m pytest — 纯逻辑的单元测试，全部使用模拟对象/固定数据运行，无需启动 ChemDraw：布局计算、样式预设、HRMS 文本、去重、编号、差异比较、RDKit 枚举、CDXML 解析/图构建、子结构/SMARTS 匹配、画布/说明文字分类、试剂文本下标格式化、键拆分，以及对 COM 工作线程内部逻辑的测试，涵盖超时/唤醒状态机和 targets.py 的目标解析及缓存过期重试逻辑。
• .venv\Scripts\python test_smoke_visual.py — 实时冒烟测试；端到端操作可见的 ChemDraw 窗口。请观察运行过程。

开发

包布局，以及此连接器针对 ChemDraw COM 的种种特性（COM 崩溃陷阱、静默无操作、时序/缓存问题）——查看源代码时请参阅 AGENTS.md，不只是要扩展代码时才看。如果你只是通过 Claude 与 MCP 服务交互（本 README 的其余部分就是介绍这一点），这些内容都无关紧要；但只要你在阅读代码，它们就是理解代码为何如此设计的最快途径。

故障排除

• 画布文本编辑尚未完成 / 文本工具仍处于激活状态 — 会使 ChemDraw 的 UI 线程陷入模态循环，从而阻塞 COM。连接器会自动恢复：超时时，它会通过 Win32 向 ChemDraw 当前聚焦的控件发送 Escape（com/nudge.py，使用独立于受阻 COM 的通道），然后重试，因此意外遗留的编辑不会再卡住会话。只有自动恢复失败时，才会出现下方的“无响应”错误。
• “ChemDraw 未响应自动化请求” — 存在模态对话框（或自动唤醒操作未能清除的编辑）；关闭对话框或按 Escape / 单击空白画布，然后重试。
• “ChemDraw 在此操作期间停止响应” — ChemDraw 崩溃后已重新启动；请从 %LOCALAPPDATA%\chemdraw-mcp\backups 中的自动备份恢复未保存的工作。
• 工具会报告形如 claude-a1b2c3d4 的结构 ID；如果某个结构“已不存在”，则说明该结构已被删除/重建——请让 Claude 调用 chemdraw_get_document_state 重新盘点页面。

许可证

MIT