ChemDraw MCP

ChemDraw MCP for macOS

Native, editable chemical drawings from your assistant or terminal. Read your unsaved ChemDraw edits, build aligned molecule tables in the same document, and export figures at a consistent chemical scale.

[Download for Mac (Apple Silicon)](https://github.com/glebo309/chemdraw-mcp-macos/releases/download/v0.10.0rc22/ChemDraw-MCP-Apple-Silicon.dmg) · Release notes · Terminal installation · Examples and customization · Architecture

Install once

All routes use the same native bridge. You do not need a separate installation for each model. Other local stdio MCP clients can use the server executable; each client's permissions and tool behavior still need testing. The graphical helper offers Claude Desktop and Codex local-client configuration. It does not install a remote connector into web ChatGPT.

Terminal quick start

git clone https://github.com/glebo309/chemdraw-mcp-macos.git

cd chemdraw-mcp-macos ./install.sh

Setup starts automatically after dependency installation. To connect assistants, use ./install.sh --client claude --client codex instead. A Git clone alone does not execute anything. Checkout commands use uv run; no global shell command or PATH change is assumed. For an optional first drawing after setup:

uv run --locked --extra chemistry chemdraw-mac first-run

Prefer no terminal? Download the Mac DMG, open it, and open ChemDraw MCP. The graphical helper includes Python and dependencies, guides the ChemDraw add-in step, and connects selected local clients. It does not install or license ChemDraw itself.

The graphical install also includes terminal access. After Finish, open a new macOS zsh Terminal window and run chemdraw-mac --help or chemdraw-mac first-run. No second download, Python or uv installation is needed. Setup preserves and backs up existing shell settings before adding its PATH entry.

Updating? No uninstall needed. Quit connected assistants and ChemDraw after saving your work, run the new DMG's setup, test, and finish. The existing add-in is refreshed in place. Setup automatically saves diagnostics on your Mac. Update instructions.

Experimental candidate: 0.10.0rc22. Requires your own licensed ChemDraw and a logged-in Mac desktop. Native tests have run on Apple Silicon, macOS 15.6, ChemDraw 23.0.1.11. The Mac app is ad-hoc signed, not Developer ID signed or notarized. Independent-Mac acceptance is still open. Only one assistant can own the native connection at a time. Compatibility · Graphical setup · Updates

Ask for the result

Draw caffeine in my current ChemDraw document.

Reviewed bundled names (currently caffeine/caffein) resolve locally, without depending on PubChem availability. Other supplied names/CAS through chemdraw_draw include PubChem lookup without another confirmation. Say "offline" or "no network" to disable provider lookup; the assistant must then pass allow_network=false. Only the supplied query is sent, not the drawing. Explicit SMILES/InChI inputs remain local.

Read my edited parent structure. Make an eight-member scope, align the common

scaffold, center the structures and captions, and add pages in this document

if needed. Do not invent yields.

Export this document as PDF and transparent 600-DPI PNGs, preserving molecular scale.

The drawing harness checks explicit graphs, native output, layout and source preservation. Shared tables use measured ink centres and common caption baselines; complete batches can add physical pages without shrinking molecules. One hidden native copy measures the table before final insertion. Physical-scale SVG/PNG exports keep bond size consistent instead of fitting every molecule to the same image width. Native PDF retains paper pages. No HTML review is required for ordinary shared drawings or physical-scale exports.

Worked examples · Drawing request format · Export settings and limits

Version rc18 adds native circled unit charges to ordinary explicit reactions, with saved ownership and bond/label clearance checks. Version rc17 batches complete explicit reactions, measures their native ink, and selects A4 or A3 paper without shrinking molecules or removing participants. Reaction exports include physical-scale SVG, 600-DPI transparent PNG and a white preview. Reaction workflow and limits.

Version rc16 introduced lighter native previews, optional canvas-only delivery, per-stage timings and validated name-lookup reuse. Fresh regular six-membered rings are axis-aligned; a live scaffold reference still takes precedence. Delivery choices · Measured performance

Control desktop ChemDraw from a terminal or an MCP-connected assistant. Create native structures and explicit reaction rows, import local styles, design mapped aromatic scopes, inspect identifiers, resolve names with explicit network opt-in, polish figures, add supported electron/charge symbols and curves, or batch-export finished drawings. Inspect native exports and keep editable output plus a chemical audit.

Native ChemDraw rendering. The desktop JavaScript API reads and appends supported molecule batches; bounded AppleScript handles other native commands and exports. RDKit supplies validated graphs and coordinates through its ChemDraw CDXML writer, not images. ChemDraw renders SVG; offline resvg rasterizes its unchanged artwork for transparent PNG. Ordinary explicit reactions use whole-document batching; advanced legacy workflows retain native import/cleanup. Natural-language interpretation comes from your MCP client, not an embedded LLM.

Independent, open-source experimental project under MIT. Native workflows require your own licensed ChemDraw installation; identifier inspection, style extraction and scope proposals are offline. MCP named drawings include PubChem lookup of the supplied query by default, with an explicit offline override. Standalone resolution and CLI lookup retain their opt-in flags. Only ChemDraw 23.0.1 has been live-tested here; individual feature evidence remains separate. Compatibility and limits

Experimental, not a stable release: native support is limited to the tested ChemDraw build and supported drawing subset. Cross-process coordination and opt-in circled charges have regression coverage; crowded charge positions fail explicitly rather than risking a changed molecular graph. See current development status for exact checks and pending acceptance on another Mac.

Two layers, one native MCP

The core MCP already works on its own. Use it to import, create, inspect, clean, style and export native ChemDraw documents. The optional workflow layer adds reusable drawing, layout and validation operations. Your connected AI client interprets natural language and chooses the tools; there is no LLM inside this server.

Both modes use the same native bridge. Full workflows accept structures and recipes, not a fixed catalogue of molecules. Experimental metal-complex work is an additional capability, not something users must wait for before using the core MCP. See architecture, installation and design principles and client configuration.

Existing document or background export

chemdraw_draw and chemdraw_draw_structures reuse a visible working document in auto mode for supported molecules and captions. Untitled documents do not need saving first. Specify presentation="shared", document_id=ID when several documents are open. Native API insertion uses planned coordinates and preservation checks in the same document, without clipboard or keyboard movement. Shared delivery requirements and limits.

Use live-read and live-action to inspect and run supported native commands on the document already open in ChemDraw, without another working window or preview. Fresh snapshots detect changed content before dispatch. visibility shows/hides one document. render --input drawing.cdxml --output /absolute/new-folder exports supplied CDXML in a hidden window and closes that owned document after success. Both MCP profiles expose matching tools.

This is on-request synchronization, not continuous collaborative editing. Arbitrary atom edits still use the separate copy workflow. Background rendering requires a logged-in licensed Mac desktop; it is not a display-free server mode. Commands, evidence and limits

Acknowledgments

Special thanks to Marco DeCorti for showing what makes a chemical drawing clear and visually polished, providing reference examples, and carefully checking the generated output. His input helped shape the project's molecular drawing style and visual quality standards.

Native before and after

Both drawings below are exports from desktop ChemDraw, not a substitute renderer. GitHub previews have a solid white background for readability in light and dark themes; original exports remain transparent. Reproduce them with the included example and recipe below.

Complete jobs and reusable lab settings

The v0.9 workflow layer connects the individual tools into callable jobs:

• Complete scope: scope-job proposes from an explicit mapped parent, requires candidate acceptance, draws and aligns the selected compounds, and lays out actual category bands with headings, dotted dividers and a shadow frame. Recipe · Guide
• Explicit reaction series: reaction-series composes up to three supplied reaction rows, including supported water/halides, ionic salts and coefficients. It does not predict products or certify balance. Guide and limits
• Owned movement and routes: build-ownership / move-owned carry explicit captions, symbols and internal curves with their molecules. suggest-routes / apply-route propose and render a selected obstacle-checked cu