{
  "markdown": "# live-chemdraw-mcp\r\n\r\n[![Tests](https://github.com/MALeitch/live-chemdraw-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/MALeitch/live-chemdraw-mcp/actions/workflows/tests.yml)\r\n\r\nMCP server that connects AI assistants to a **live ChemDraw window** on\r\nWindows via COM automation — draw, edit, and organize structures directly in\r\nthe document you have open.\r\n\r\n**Capabilities:**\r\n- **Insert & export** — SMILES, name, molfile, InChI, CDXML; export as an\r\n  image, structure text, or straight to the clipboard\r\n- **Substrate-scope tables** — build a whole scope figure in one call, sized\r\n  for journal columns, with labels/yields placed under each structure\r\n- **Shorthand groups** — detect and contract functional groups inline\r\n  (`chemdraw_contract_group`: Ph, TES, Boc, Ts... ~40 groups, SMARTS-matched\r\n  via RDKit), or contract/expand a whole structure to a single label,\r\n  including a one-call bulk expand across the whole document\r\n- **Figure layout** — `chemdraw_describe_canvas` gives one semantic read of a\r\n  whole page (structures, captions matched to their owners, panel boxes,\r\n  overlap/overflow violations); `chemdraw_arrange_in_region` fits structures\r\n  into a panel box in one call, captions riding along, nothing ever\r\n  rescaled; `chemdraw_get_layout`/`chemdraw_move_objects` for raw-geometry\r\n  plans with automatic collateral-movement detection\r\n- **Chemistry QC** — read/set stereochemistry (wedge/hash, \"and1\"/\"or1\"\r\n  enhanced-stereo grouping), duplicate detection, valence warnings, IUPAC\r\n  naming, HRMS text generation\r\n- **Publication tools** — journal style presets, reaction schemes, and\r\n  derivative-library enumeration with RDKit-computed properties\r\n- **Annotations** — mechanism/reaction arrows (`chemdraw_make_arrow`: solid/\r\n  hollow/angle heads, single-barb \"fishhook\" electron-pushing arrows,\r\n  crossed-out \"no-go\" pathway markers, dipole markers) and symbols\r\n  (`chemdraw_make_symbol`: racemic/absolute/relative stereo-descriptor\r\n  labels; lone pairs/radicals/daggers also place but currently render at a\r\n  tiny, apparently unscalable default size — see the tool's own docstring).\r\n  Isotope labeling (`chemdraw_edit_atom(..., isotope=13, ...)`) survives\r\n  export as real isotope notation, not just a ChemDraw-display label.\r\n  **Limitation:** arrows/symbols are free-floating — moving a nearby\r\n  structure with `chemdraw_move_objects`/`chemdraw_transform` will NOT carry\r\n  them along, the same class of gap already documented for captions below.\r\n  Curved/arc arrows and true double-object ⇌ equilibrium-arrow pairs aren't\r\n  supported yet — both were probed live and need more COM investigation\r\n  before a design commitment (see `docs/com_typelib/`)\r\n- **Polymer repeat-unit brackets** (`chemdraw_make_bracket`: square/curly/\r\n  round glyph, SRU/monomer/copolymer/crosslink/... usage with ChemDraw's own\r\n  auto-generated abbreviation label — \"n\"/\"mon\"/\"xl\"/etc.) wraps a structure\r\n  (or an explicit rectangle) with an opening + closing bracket pair.\r\n  **Limitations, confirmed live, not solved:** RepeatCount/SRULabel/\r\n  ComponentOrder cannot be set via COM at all (both get and put reliably\r\n  raise); the pair's mirrored orientation (\"[...]\" vs two identically-\r\n  oriented marks) is unreliable once a second bracket exists in one\r\n  automation session — always check the exported image; brackets are\r\n  purely decorative (not bound to real atom/bond membership despite\r\n  ChemDraw exposing InsideAtoms/ContainedAtoms/CrossingBonds properties —\r\n  confirmed these don't reflect true geometry) and share the same\r\n  free-floating/doesn't-move-with-the-structure limitation as arrows/\r\n  symbols above\r\n- **TLC plates** (`chemdraw_make_tlc_plate`: rectangular plate outline with\r\n  labeled Rf-spot lanes for reaction-monitoring figures) — a spot's vertical\r\n  position is driven entirely by its `rf` (0-1) property, which ChemDraw\r\n  itself interpolates between the plate's origin/solvent-front lines\r\n  (confirmed live via measured screenshot pixel positions, within ~1% of\r\n  the expected fraction) — no manual position math needed. Supports\r\n  `show_rf` (auto \"Rf = 0.NN\" label), `filled`/`bold`/`dashed` (a hollow\r\n  dashed-outline circle is visually confirmed distinct from a solid dot),\r\n  and an experimental `tail` (comet-tail smear) whose visual effect could\r\n  not be confirmed at available screenshot resolution. **Hard limit,\r\n  confirmed live and enforced by the tool (raises before any COM call): a\r\n  single lane can hold at most 2 spots** — ChemDraw's own `AddSpot` is a\r\n  silent no-op past that, with no error at all. Same free-floating/\r\n  doesn't-move-with-the-structure limitation as arrows/symbols/brackets\r\n  above.\r\n\r\nThis README covers setup and usage — not a per-tool reference (each tool's\r\nexact parameters, return shape, and usage notes live in its own docstring,\r\nvisible to any MCP client via its tool listing) and not internal\r\narchitecture or ChemDraw-COM implementation notes (see\r\n[`AGENTS.md`](AGENTS.md) for those — useful reading whenever you're\r\nlooking at the source, whether you're debugging something, curious how\r\nit works, or extending it, not only for the last one).\r\n\r\nBuilt and validated against **ChemDraw 26 (Revvity)** on Windows 11 /\r\nPython 3.14.\r\n\r\n> This is an independent, unofficial project. It is not affiliated with,\r\n> endorsed by, or supported by Revvity or PerkinElmer. \"ChemDraw\" is a\r\n> trademark of its respective owner; it's referenced here only to describe\r\n> compatibility. You'll need your own licensed copy of ChemDraw to use this.\r\n\r\n## Setup\r\n\r\n```powershell\r\ncd live-chemdraw-mcp\r\npython -m venv .venv\r\n.venv\\Scripts\\python -m pip install pywin32 rdkit \"mcp[cli]\" pytest\r\n```\r\n\r\nRegister in `%APPDATA%\\Claude\\claude_desktop_config.json` (replace\r\n`C:\\\\path\\\\to\\\\live-chemdraw-mcp` with wherever you cloned it):\r\n\r\n```json\r\n\"mcpServers\": {\r\n  \"chemdraw\": {\r\n    \"command\": \"C:\\\\path\\\\to\\\\live-chemdraw-mcp\\\\.venv\\\\Scripts\\\\python.exe\",\r\n    \"args\": [\"C:\\\\path\\\\to\\\\live-chemdraw-mcp\\\\server.py\"]\r\n  }\r\n}\r\n```\r\n\r\nRestart the Claude desktop app. No ChemDraw-side installation is needed — the\r\nserver attaches to a running ChemDraw (or launches one) over COM.\r\n\r\n## Testing\r\n\r\n- `.venv\\Scripts\\python -m pytest` — unit tests for the pure logic, all\r\n  running against fakes/fixtures with no live ChemDraw required: layout\r\n  math, style presets, HRMS text, dedup, numbering, diff, RDKit\r\n  enumeration, CDXML parsing/graph-building, substructure/SMARTS matching,\r\n  canvas/caption classification, reagent-text subscript formatting, and\r\n  bond-splitting, plus connector-internals coverage for the COM worker's\r\n  timeout/nudge state machine and `targets.py`'s target-resolution and\r\n  stale-cache-retry logic.\r\n- `.venv\\Scripts\\python test_smoke_visual.py` — live smoke test; drives a\r\n  visible ChemDraw window end to end. Watch it run.\r\n\r\n## Development\r\n\r\nPackage layout, and the ChemDraw COM quirks this connector was built\r\naround (COM crash traps, silent no-ops, timing/caching gotchas) — see\r\n[`AGENTS.md`](AGENTS.md) whenever you're looking at the source, not only\r\nif you're extending it. None of it matters if you're just talking to the\r\nserver through Claude (that's what the rest of this README covers), but\r\nit's the fastest way to understand why the code is shaped the way it is\r\nif you're reading it for any reason.\r\n\r\n## Troubleshooting\r\n\r\n- **In-progress canvas text edit / text tool left active** — puts ChemDraw's\r\n  UI thread in a modal loop that blocks COM. The connector auto-recovers: on a\r\n  timeout it posts an Escape to ChemDraw's focused control via Win32\r\n  (`com/nudge.py`, a channel separate from the blocked COM one) and retries,\r\n  so a stray edit no longer wedges the session. Only if that fails do you see\r\n  the \"not responding\" error below.\r\n- **\"ChemDraw is not responding to automation\"** — a modal dialog is open (or\r\n  an edit the auto-nudge couldn't clear); dismiss the dialog or press Escape /\r\n  click empty canvas, then retry.\r\n- **\"ChemDraw stopped responding during this operation\"** — ChemDraw crashed\r\n  and was relaunched; recover unsaved work from the automatic backups at\r\n  `%LOCALAPPDATA%\\chemdraw-mcp\\backups`.\r\n- Tools report structure ids like `claude-a1b2c3d4`; if one \"no longer\r\n  exists,\" the structure was deleted/rebuilt — ask Claude to call\r\n  `chemdraw_get_document_state` to re-inventory the page.\r\n\r\n## License\r\n\r\n[MIT](LICENSE)\r\n",
  "bytes": 8440,
  "sha": "0053ed4932bf6a09269b81ed8b7f8906ab40253388acaf8f55e0e89e01ad7975",
  "repo_slug": "maleitch/live-chemdraw-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_maleitch_live_chemdraw_mcp_6d5a5505/readme"
}