English · Simplified Chinese

CDXML Toolkit — ChemDraw MCP Server and Python Chemical Drawing

Platform support: Portable CDXML and RDKit workflows run on Windows, macOS, and Linux. ChemDraw COM rendering, ChemScript, and editable ChemDraw objects in Word or PowerPoint require a Windows host with a licensed desktop ChemDraw installation.

Featured demos

Explore real paper images and data through native previews, reference comparisons and editable downloads.

Twenty structures: resolving stereo-reader disagreement

The source-oriented reconstruction disagreed between ChemScript and RDKit for 16 structures. The saved interoperability revision agrees for 20/20, preserving the reviewed molecular targets. Compound 1 uses explicit stereobonds and therefore differs visually from the source. Same-scale ink IoU: 0.6960; this is not pixel-identical or independent experimental stereo validation.

Editable CDXML · Failure analysis, workflow and rights · Per-compound evidence and versions

The embedded X-ray is a source crop. Paper-derived artwork is excluded from the MIT license; see the case's source and rights statement.

Incremental workflow available: linked structure/scene records, verified candidate caching, local checks and explicit dual-variant acceptance. A controlled three-caption-edit replay reduced native calls from 8 to 2 (33.53 s to 8.88 s); this is not an end-to-end recognition speed claim. Source-oriented version · Workflow · Measured evidence.

Paper reaction scheme

Turn a published reaction scheme into an editable ChemDraw document. This example preserves the five structures, reaction conditions, yields and compound labels shown in the reference image.

Original paper figure

Editable reconstruction — ChemDraw-native output

Download editable CDXML · Inspect structure-by-structure comparisons · Source and verification details

Structures extracted from the saved CDXML match the five reviewed reference structures. The shared wavy bond for 17a/17b remains unspecified, as in the original figure.

Visually reviewed and editable; not pixel-identical. Font metrics, arrows and some line geometry still differ. Matching saved structures does not independently prove that every detail was recognized correctly.

Sceptrin mechanism

Reference excerpt

ChemDraw reconstruction

Editable CDXML · Native CDX · Side-by-side comparison · Verification and source limitations

Eight numbered structures and six chloride counterions retain their molecular inventory, depicted stereochemistry and formal charges through an actual ChemDraw CDXML → CDX → CDXML save cycle. Undefined R groups remain generic substituents. The reconstruction is visually reviewed, not pixel-identical: font metrics, electron-arrow paths, some bridge geometry and the placement of the delocalized charge indicators differ. The source's cropped recrystallization statement is not completed by inference.

Native TLC

Native TLC plate, lane and spot objects with illustrative Rf values.

Editable CDXML · Run this example · Data and template provenance

Native apparatus

Built from installed ChemDraw apparatus templates, preserving their editable native artwork.

Editable CDXML · Run this example · Data and template provenance

Experimental NMR

Real processed 1D NMR data, with peak picking and selected-region integration available. No automatic atom assignment.

Editable CDXML · Run this example · Data and template provenance

Simulated reaction kinetics

Explicitly simulated first-order decay demonstrates the numerical-data-to-figure workflow.

Editable CDXML · Run this example · Data and template provenance

Complex synthesis: 101–112

Full scheme with editable structures. Includes every compound number, reaction condition and mechanism arrow. Native saving preserves connectivity, charge, isotopes and alkene geometry. Bridgehead stereochemistry remains unresolved, and font and line geometry differ; this is not a validated 1:1 reproduction.

Full editable CDXML · Reference comparison · Acceptance and provenance

Complex synthesis: 113–122

Full scheme with editable structures. Includes every compound number, reaction condition and mechanism arrow. Native saving preserves connectivity, charge, isotopes and alkene geometry. Bridgehead stereochemistry remains unresolved, and font and line geometry differ; this is not a validated 1:1 reproduction.

Full editable CDXML · Reference comparison · Acceptance and provenance

Related MCP server: chemdraw-mcp

Reconstruction scope and structure review

Both complex synthesis examples contain the complete layout, native molecular structures, text, brackets and electron arrows. Molecules remain editable atoms, bonds and expandable abbreviations; screenshots and traced outlines do not substitute for molecular objects.

Save-cycle agreement does not establish perfect recognition of the reference. Compounds 105–109, 115–120 and 121 contain conflicting specified configurations; some expanded chains and abbreviation definitions in the source also need clarification. The reconstructions preserve each depiction rather than silently making the route chemically self-consistent. The atom-level comparison records component hashes and atom mappings for review; absence of a disagreement does not independently establish source stereochemistry.

After installing the runtime, rebuild these two layouts offline without repeating DECIMER recognition:

python examples/paper-reconstructions/rebuild.py ./paper-figures-output

Use a new output directory. This assembles saved molecular components; native previews still require Windows ChemDraw. See the rebuild example and limitations. Source paper artwork is not relicensed under the software license.

Publication figures

Create editable figures with explicit atom coordinates, six reaction-arrow styles, electron arrows, rich conditions, atom numbering and native-template preservation.

The renderer checks chemical identity by extracting structures from the saved CDXML. Wavy bonds remain unspecified; enhanced AND/OR/ABS stereo groups are retained. Chemistry checks and visual similarity are separate: neither a valid SMILES nor a low image-difference score proves a faithful paper reproduction. Unsupported fresh radical and non-tetrahedral depictions require a verified native template.

Installation: these features require the source version installed by the Quick Start commands; they are not included in the v0.7.0a1 release.

What it provides

Source and release identity

The current source prepares 0.7.0a2; a local checkout is not evidence that this version has been published. The existing v0.7.0a1 release predates publication-figure and incremental-reconstruction support. For reproducibility, record the full source commit or wheel hash as well as the version.

get_toolkit_capabilities(detail="summary") reports the selected profile, source runtime_identity.version, and runtime_identity.code_sha256, separately from installed distribution metadata. The digest covers normalized Python sources, not dependencies or all package data. It identifies code edits without including molecule contents. A metadata mismatch warning means the editable checkout or installed package needs reinstalling; it is not an installation success claim.

Business results with an explicit top-level ok=false propagate as MCP tool errors and failed calls in metrics. Reports successfully generated with individual checks marked failed/not-run retain those separate acceptance states. Default worker timeouts use the registered tool limit, then the global environment/default; an explicit per-call timeout takes precedence.

Quick start

Required: 64-bit Python 3.10–3.13. Portable CDXML and RDKit operations run without ChemDraw. Native rendering, ChemScript, and editable Office objects require Windows plus a licensed desktop ChemDraw installation. Python 3.14 is not supported yet.

conda create -n cdxml python=3.12 pip -y
conda activate cdxml

git clone https://github.com/ZiChenWang114514/cdxml-toolkit-community.git
Set-Location .\cdxml-toolkit-community

# Both distributions expose the cdxml_toolkit import package.
pip uninstall -y cdxml-toolkit
pip install -e ".[all]"

# Read-only environment and capability report.
cdxml-doctor --no-tests

The default installation includes the portable CDXML, RDKit, and MCP runtime. Optional groups are windows, office, chemscript, analysis, scientific, image, decimer, opsin, http, all, and dev.

Install the current community source directly when a checkout is unnecessary:

pip install "cdxml-toolkit-community[all] @ git+https://github.com/ZiChenWang114514/cdxml-toolkit-community.git@main"

cdxml-doctor --no-tests does not change the machine. To detect ChemDraw and prepare a compatible ChemScript environment interactively, run:

cdxml-doctor --no-tests --configure-chemscript
cdxml-doctor --json

ChemScript is optional. OPSIN provides offline IUPAC name resolution when Java is available. The wheel does not bundle a JRE; the runtime first checks JAVA_HOME and java on PATH. A pre-approved local archive can be installed with explicit integrity metadata:

$env:CDXML_TOOLKIT_JRE_ZIP = "C:\installers\temurin-jre.zip"
$env:CDXML_TOOLKIT_JRE_SHA256 = "approved sha256"
cdxml-doctor --no-tests

Archive size, extracted size, paths, links, and optional SHA-256 are checked before installation.

Connect an agent

Any MCP-compatible agent can connect to the runtime. Start the full 39-tool stdio service:

cdxml-mcp

Register the Python interpreter and arguments in your client's MCP configuration. A common JSON format is:

{
  "mcpServers": {
    "chemdraw": {
      "command": "C:\\Users\\YOU\\miniconda3\\envs\\cdxml\\python.exe",
      "args": ["-m", "cdxml_toolkit.mcp_runtime"]
    }
  }
}

Configuration location and syntax depend on the client. Restart the agent, then try:

Resolve aspirin, draw it as CDXML, and render a PNG preview.

For paper reconstruction and laboratory figures, load the client-independent ChemDraw Skill. The historical profile identifier codex remains available for compatibility; it does not restrict which agent can use the tools.

Copy CLAUDE.md into an agent workspace when the client supports project instructions. It tells the agent to obtain molecular structures from tools, use OCSR for images, preserve chemical semantics, and verify transformations instead of inventing structure strings.

How the runtime works

Important runtime properties:

• Tool calls run in subprocess workers with configurable hard timeouts and structured errors.

• ChemDraw, Word, and PowerPoint automation share serialized native-resource coordination.

• Output-producing tools validate artifacts and avoid unintentionally replacing existing files.

• Metrics record counts, duration, timeouts, worker failures, and queue length without tool arguments or molecular content.

• get_toolkit_capabilities reports the available local features before an agent chooses a workflow.

Tool profiles

Choose the smallest useful profile to reduce tool-selection noise:

The generated MCP tool reference and JSON schema contain the exact live signatures. CI checks both files for drift.

Streamable HTTP

Stdio remains the local default. An activated Windows workstation can serve a trusted remote computer after installing the http extra:

$env:CHEMDRAW_MCP_HTTP_API_KEY = "generate-a-long-random-value"
cdxml-mcp --transport streamable-http --host 0.0.0.0 --port 8029 `
  --allowed-host chemdraw-host.example:8029 `
  --allowed-origin https://trusted-client.example

Remote binding requires a bearer key and an explicit host list. /health contains no molecule data; /metrics requires authentication when the server is remotely reachable.

DECIMER image upload is disabled by default. Remote recognition requires confirm_upload=true, validates that the payload decodes as an image, and enforces request and response limits.

Command line

The scheme renderer accepts YAML, reaction JSON, and a compact text syntax described in the showcase catalog.

Development

python -m pip install -e ".[dev,windows,office,analysis,image,scientific]"
python -m pytest -m "not network" -q
python -m build
python -m twine check dist/*

Hosted CI checks Python 3.10–3.13, MCP SDK 1.x and 2.x, generated references, portable tests, and distributions. Native ChemDraw, ChemScript, Word, and PowerPoint checks run on a licensed Windows workstation.

Read the contribution guide, security policy, and maintenance guide before proposing or releasing changes.

Community stewardship

This repository continues leehiufung911/cdxml-toolkit. The distribution is cdxml-toolkit-community; the compatible Python import remains cdxml_toolkit.

• Community maintainer: ZiChenWang114514

• Original author: Hiu Fung Kevin Lee (@leehiufung911)

• Third-party data and component notices: NOTICE.md

• License: MIT

The original project was directed by Hiu Fung Kevin Lee, a PhD organic chemist, and documented as built and tested with Claude Code (Opus 4.6).

Data-driven publication figures

Create substrate-scope and full-structure SAR panels from CSV/XLSX and trusted structures. Stable compound IDs bind measurements to editable ChemDraw objects. Update data or replace a structure after native editing while preserving unrelated layout and annotations; ambiguous matches produce conflict drafts. See the workflow and examples. XLSX support requires the toolkit publication extra.